Skip to main content

Full text of "ibm :: 360 :: os :: tcam :: GC30-2024-3 OS MFT and OS MVT TCAM Programmers Guide Rel 21 Jul72"

See other formats


CX:30-2024.3 



OS/MFT and OS/MVT 
TCAM Programmer's Guide 



I 



m 




GC30-2024-3 



OS/MFT and OS/MVT 
Systems TCAM Programmer's Guide 

Program No. 360S-CQ-548 



OS Release 21.0 





Fourth Edition (July 1972) 

This publication is a major revision of, and obsoletes, GC30-2024-2 and Technical Newsletter 
GN30-2573; it provides function support of OS Release 21.0 (Component Release 4 of TCAM), 
and maintenance support of TCAM in OS Release 21.0 until otherwise indicated in new editions 
or Technical Newsletters. Changes appearing in this edition are listed in the Summary of 
Amendments following the Preface . Changes are made periodically to the information herein; 
before using this publication with IBM systems or equipment, refer to the latest SRL Newsletter 
for editions that are applicable and current. 

Requests for copies of IBM publications should be made to your IBM representative or to the 
IBM branch office serving you locality. 

This manual has been prepared by the IBM Systems Development Division, Publications 
Center, Department EOl, P.O. Box 12275, Research Triangle Park, North Carolina 27709. A 
form for reader's comments is provided at the back of this publication. If the form has been 
moved, comments may be sent to the above address. Comments become the property of IBM. 



© Copyright International Business Machines Corporation 1972 



Preface 

The first section of this book, How to Use This Book defines the audience for 
which this programmer's guide is intended, explains how the book is organized, 
and suggests how the reader might best famiUarize himself with its contents. The 
chart below hsts alphabetically the key words that are used throughout the book 
to refer to other publications; accompanying the key words are the corresponding 
title and order number to which the key words refer. 



Key Words Used in 
This Publication 


Title 


Order No. 


Assembler 
Language 


IBM System/360 Operating System 
Assembler Language 


GC28-6514 


Checkpoint/ Restart 
Planning Guide 


IBM System/360 Operating System 
Advanced Checkpoint/Restart 


GC28-6708 


Data Management 
Services 


IBM System/360 Operating System 
Data Management Services 


GC26-3746 


Job Control 
Language 


•IBM System/360 Operating System 
JCL User's Reference 


GC28-6704 


Messages and Codes 


IBM System/360 Operating System 
Messages and Codes 


GC28-6631 


Operator's Guide 


IBM System/360 Operating System 
Operator's Reference Manual 


GC28-6691 


TCAM User's 
Guide 


OS TCAM User's Guide 


GC30-2025 


Principles of 
Operation 


IBM System/360 Operating System 
Principles of Operation 


GA22-6821 


Programmer's Guide 
to Debugging 


IBM System/360 Operating System 
Programmer's Guide to Debugging 


GC28-6670 



lU 



Supervisor and Data 
Management Macro 
Instructions 



IBM System/360 Operating System 
Data Management Macro Instructions 



GC26-3794 



Supervisor Services 


IBM System/360 Operating System 
Supervisor Services and Macros 


GC28-6646 


System Generation 


IBM System/360 Operating System 
System Generation 


GC28-6554 


TCAM Concepts and 
Facilities 


OS TCAM Concepts and Facilities 


GC30-2022 



TCAM Level 4 
Component Release 
Guide 



TCAM Level 4 Component Release 
Guide 



GC30-1007 



TCAM PLM 


OS/MFT and OS/MVT TCAM Logic 


GY30-2029 


TSO Command 
Language 


IBM System/360 Operating System 
TSO Command Language Reference 


GC28-6732 


TSO Guide 


IBM System/360 Operating System 
TSO Guide 


GC28-6698 


Utilities 


IBM System/360 Operating System 
Utilities 


GC28-6586 



Summary of Amendments 



This revised edition incorporates the following programming information that 
applies to OS Release 21.0 (Component Release 4 of OS/MFT and OS/MVT 
TCAM): 

2790 Data Communications System support. 

3270 Information Display System support. 

3670 Brokerage Terminal support. 

7770 enhancements. 

BSCl, BSC2, BSC3 device types. 

Disk error handling. 

General Poll for 2260 and 3270. 

Reverse Interrupt (RVI) support. 

TOTE II On-Line Test facility (OLT). 

TSO/TCAM Mixed Environment and 3270 support. 

Macros changed: 



DATETIME 
ERRORMSG 
FORWARD 
GET 
INTRO 
INVLIST 
LOCK 
LOCOPT 
New macros: 
COMMBUF 



MSGFORM 

MSGTYPE 

ORIGIN 

POINT 

PUT 

QACYION 

QCOPY 

SCREEN 

QRESET 



SETEOM 

TERMINAL 

TPROCESS 

TTABLE 

UNLOCK 

WRITE 



MHGET SLOWPOLL 

MHPUT TYPETABL 

• New operator commands: 

GENPOLOFF GENPOLON 

Also included are minor corrections and format changes throughout the pubUca- 
tion that apply to maintenance support of OS/MFT and OS/MVT TCAM in OS 
Release 21.0. The previous edition of this manual, GC30-2024-2, incorporated 
the following information that applies to OS Release 20.7 (Component Release 2 
of OS/MFT and OS/MVT TCAM): 

• Defining logical messages (see Handling Logical Messages) . 

• Concen^trating and deconcentrating messages (see Appendix J ). 

• Recovering from text errors in multiblock messages (see Mid-Batch Recovery ). 

• Editing data across buffer boundaries (see the MSGEDIT functional MH 
macro). 

• Removing line-control characters on a count basis from incoming messages and 
permitting variable-length reblocking of records for outgoing messages (see the 
MSGFORM functional MH macro). 

• Retrying to dial a switched station (see the RETRY functional MH macro). 

• Determining how many complete messages are queued for the apphcation 
program (see the MCOUNT application program macro). 

• Recording date and time that messages are received at the apphcation program 
(see the TPDATE application program macro). 

• Including the IBM 3735 Programmable Buffered Terminal in a TCAM net- 
work. 

• Including the Attention Interrupt feature for the IBM 1050 and 2741 terminals. 



Contents 



How to Use This Book 1 

Writing the Message Control Program 3 

What the Message Control Program is 3 

Functions of the MCP 3 

User Tasks in Writing the MCP 4 

Defining Terminal-and Line-Control Areas 5 

Terminology 5 

Line Control 5 

Establishing Contact 9 

Invitation 9 

Constructing the Invitation List 10 

INVLIST Macro Instruction 11 

Nonswitched Point-to-Point or Multipoint Lines to Stations Using 

Polling Characters 14 

Switched Lines To Terminals Using Polling Characters 15 

Switched Lines to Stations Using ID Sequences 15 

Switched or Nonswitched Contention Lines to Terminals Not 

Assigned ID Sequences 17 

Output-Only Lines to Stations Having no ID Sequences Assigned 

to Them 17 

Selection 18 

Constructing the Terminal Table 18 

TTABLE Macro Instruction 20 

OPTION Macro Instruction 21 

TERMINAL Macro Instruction 25 

Coding the TERMINAL Macro for a Component 37 

Coding the TERMINAL Macro for a Line 38 

TLIST Macro Instruction 43 

TPROCESS Macro Instruction 45 

LOGTYPE Macro Instruction 51 

Maintaining Orderly Message Flow 52 

Message Priority and Queuing 52 

Transmission Priority 55 

Transmission Priority for Nonswitched Polled Stations 55 

Transmission Priority for Nonswitched Polled Stations Using 

TCAM's Buffering Feature 57 

Transmission Priority for Nonswitched Contention Stations 58 

Transmission Priority for Switched Stations 58 

Calls between the Computer and a Switched Station 59 

The System Interval 61 

Defining Buffers 63 

Structure of a Buffer 63 

The Buffer-Unit Pool 65 

Buffer Definition Checklist 69 

Design Considerations 70 

Size of Buffers 71 

Number of Units 72 

Size of Units 72 

Dynamic and Static Buffer Allocation 73 

Initial and Maximum Number of Buffers per Line 74 

Other Buffer Design Considerations 75 

Defining the MCP Data Sets 77 

Line Group Data Sets 77 

Characteristics of a Line Group 77 

Creating a Line Group Data Set 77 

Line Group DCB Macro Instruction 79 

DD Statements for a Line Group 86 

Message Queues Data Sets 88 

Disk Queuing 88 



Advantages and Disavantages of Disk Queuing . 89 

Specifying Channel Program Blocks 89 

How to Determine if too Many CPBs were Specified on the 

CPB= Operand of the INTRO Macro Instruction 91 

How to Determine if too few CPBs were Specified on the 

CPB= Operand of the INTRO Macro Instruction 91 

Preformatting DASD Message Queues Data Sets 92 

Using Multiple Arm Support 92 

Reusable Disk Queues 93 

Nonreusable Disk Queues 96 

Main-Storage Queuing 96 

Specifying One or More Queuing Methods 99 

Message Queues DCB Macro Instruction 102 

DD Statements for Message Queues Data Sets 104 

Checkpoint Data Set 104 

Checkpoint DCB Macro Instruction 105 

DD Statement for the Checkpoint Data Set 106 

Log Data Sets 107 

User ABEND Exits 108 

Activating and Deactivating the Message Control Program Ill 

Starting and Restarting TCAM 1 1 1 

Initialization and Activation Ill 

INTRO Macro Instruction 113 

OPEN Macro Instruction 127 

READY Macro Instruction 130 

Deactivation 131 

Types of Closedown 131 

Deactivating a TCAM System Without Application Program 132 

Deactivating a TCAM System With AppUcation Programs 132 

CLOSE Macro Instruction 134 

Sample MCP Activation and Deactivation Section 134 

Designing the Message Handler 137 

Message Format 137 

The Message Header 138 

Functions Performed by MH Subgroups 140 

Selecting Message-Handler Functions 145 

MH Functions and Macros Defining the Functions 145 

Message Editing 145 

Validity Checking 146 

Message Routing 146 

Record Keeping 147 

Error Handling 147 

System Control 148 

Function Modification 149 

Delimiting Functions 149 

Order of Macro Specification 149 

The Scan Pointer 149 

Handling Logical Messages 152 

Logical Message Formats 153 

Blocking Incoming Messages 153 

Deblocking Incoming Messages 154 

Converting Incoming Data to Logical Messages 154 

Logical Message Flow Within the System 155 

Message Headers for Logical Messages 158 

Coding Considerations for Logical Message Use 160 

Message Flow through a Message Handler 165 

Message Flow within an MH Group 166 

Multiple-Buffer Header Handhng 169 

Variable Processing within a Message Handler 172 

Conditional Execution of Message Handler Functional Macros 173 

User Code in a Message Handler 175 

General Requirements and Restrictions 175 

Multiple-Buffer Header Considerations 175 

Including an Open Subroutine 176 

Including a Closed Subroutine 177 



viu 



Using LOCOPT to Locate an Option Field 179 

Using SETSCAN to Locate a Header Field 179 

Using MSGTYPE to Locate a Header Field 179 

Using the FARM Parameter of the EXEC Job Control Statement 182 

Message-Handler Macro Return Codes 182 

Message Translation 186 

Using TCAM's Hold/Release Facility to Protect Outgoing Messages from 

Loss 189 

Coding the Message Handler for an Application Program 189 

Design Steps 190 

Delimiter Macro Instructions 191 

STARTMH 193 

INBLOCK 199 

INHDR ^ 200 

INBUF 201 

INMSG 202 

INEND 203 

OUTHDR 204 

OUTBUF 205 

OUTMSG 206 

OUTEND 207 

Functional Macro Instructions 209 

CANCELMG 210 

CHECKPT 212 

CODE 213 

COMMBUF 217 

COUNTER 219 

CUTOFF 221 

DATETIME 223 

ERRORMSG 225 

FORWARD 229 

HOLD 234 

INITIATE 238 

LOCK 241 

LOCOPT 244 

LOG 245 

MHGET 247 

MHPUT 249 

MSGEDIT 252 

MSGFORM 266 

MSGGEN 269 

MSGLIMIT 273 

MSGTYPE 275 

ORIGIN 280 

PATH 282 

PRIORITY 286 

REDIRECT 290 

RETRY 292 

SCREEN 293 

SEQUENCE 297 

SETEOF 299 

SETEOM 301 

SETSCAN 304 

SLOWPOLL 309 

TERRSET 311 

TYPETABL 313 

UNLOCK 314 

Putting the MCP Together 317 

Arranging the Sections of the MCP 317 

Assembling, Link-editing, and Executing the Message Control Program 318 

Assembling an MCP 318 

Link-editing an MCP 318 

Executing an MCP 318 

Sample MCPs 320 

Message Switching Between Terminal Types 321 



Inquiry and Response 328 

File Updating with Checkpoint Coordination 339 

Writing TCAM-Compatible Application Programs 353 

Message Flow to an Application Program 355 

Overview of the MCP/ Application-Program Interface 356 

Defining the Components of the Interface 358 

Defining the Application Program Data Sets and the Process 

Control Block 358 

Input DCB Macro Instruction 361 

Output DCB Macro Instruction 367 

DD Statements for the Input and Output Data Sets 370 

PCB Macro Instruction 372 

Defining Buffers for the Application Program 374 

Defining Application-Program Buffers 374 

Application-Program Buffer Design Considerations 375 

Activating and Deactivating the Application-Program Interface 377 

OPEN Macro Instruction for the Application Program 378 

CLOSE Macro Instruction for the Application Program 380 

MCPCLOSE Macro Instruction 381 

Transfering Data Between an MCP and an Application Program 382 

Defining the Application-Program Work Area 383 

Static Work-Area Definition 383 

Dynamic Work-Area Definition 383 

Moving Data Between Input and Output Work Area 384 

Defining Optional Fields in the Work Area 384 

Specifying Application-Program Work Units 387 

Work-Unit Formats 388 

Work-Unit Types 390 

Signaling End of File and End of Message 394 

Coding TCAM's Data Transfer Macros 395 

GET Macro Instruction (QSAM only) 396 

PUT Macro Instruction (QSAM only) 398 

READ Macro Instruction (BSAM only) 400 

WRITE Macro Instruction (BSAM only) 403 

CHECK Macro Instruction (BSAM only) 406 

MCOUNT Macro 409 

TPDATE Macro 410 

Multiple-Wait Capability 411 

Application-Program Error Exits 412 

Input to the SYN AD Routine 413 

SYNADAF 414 

Network Control Facilities 415 

TCOPY Macro Instruction 417 

ICOPY Macro Instruction 420 

QCOPY Macro Instruction 424 

TCHNG Macro Instruction 426 

ICHNG Macro Instruction 428 

MRELEASE Macro Instruction 431 

TCAM's Message Retrieval Facility 432 

POINT Macro Instruction 433 

TCAM's Inquiry/Response Facilities 435 

Line Lock 435 

Terminal Lock 439 

TCAM's Queue Reset Facility 440 

QRESET Macro Instruction 443 

TCAM/SAM Compatibility 445 

Coordinating TCAM Checkpoints of the MCP with OS Checkpoints of the 

Application Programs 446 

Using the CKREQ Macro Instruction for Coordination 446 

Using the DCB Exit for Coordination 449 

Coordinating MCP and Application-Program Restarts 450 

Using TCAM Service Facilities 453 

Operator Control 453 

Initialization for Operator Control 453 

General Format of Operator Commands 453 



Specifying Operator Commands 456 

Entering Operator Commands from an Application Program 458 

Incorrect Messages 458 

Operator Commands 459 

Checkpointing Operator Commands 490 

Disk Error Handling 491 

TCAM I/O Error-Recovery Procedures 491 

Mid-Batch Recovery 493 

Recovery on Input 494 

Recovery on Output 494 

TCAM I/O Error-Recording Facility 495 

Kinds of TCAM I/O Error Records 495 

Intensive-Mode Error Recording 496 

Operator Awareness Message 497 

Gaining Access to Error Records 498 

Network Reconfiguration 498 

By Operator Commands 498 

By Application Program Macros 498 

TCAM Checkpoint/Restart Facility 499 

How the TCAM Checkpoint Facility Works 502 

How to Get the TCAM Checkpoint Facility 509 

Types of TCAM Restart 512 

Using TCAM's Message Logging Facility 514 

Uses of Message Logging 514 

How Message Logging Works 515 

How to Set Up a Message Logging Facility 515 

Debugging Aids 517 

Cross-Reference Table 518 

TCAM Line I/O Interrupt Trace Table 519 

Dispatcher Subtask Trace Table 521 

Buffer Trace 523 

Writing Line Trace, STCB Trace, and Buffers to a Disk Data Set 523 

COMEDIT Printing Utility 526 

Message Queues Data Set Dump 528 

On-Line Test Function 530 

Advantages of TOTE 531 

Devices Supported 532 

System Requirements 532 

Main-Storage Requirements 533 

Coding Requirements 533 

TOTE Requirements 534 

Hardware Requirements 534 

Scheduling and Loading Unit Tests 534 

Prompting 535 

Asynchronous Test Handling 535 

OS/SYSGEN Requirements 536 

JCL Requirements for TOTE/OLTs 537 

System Preparation 539 

Machine and De^vice Requirements 539 

Control Units and Terminal Types Supported 539 

Multiprocessing System 539 

System Generation Considerations 540 

Preformatting DASD Message Queues Data Sets 543 

Appendix A: TCAM Macro Formats 545 

Appendix B: Message Error Record 547 

Appendix C: How to Make Transient Checkpoint and Operator Control 
Modules Resident 551 

Appendix D: Internal and Transmission Code Charts 555 

Appendix E: Running QTAM Application Programs under TCAM 585 

Appendix F: Summary of Operator Commands Classified by Operation 587 



Appendix G: Device-Dependent Considerations 589 

Appendix H: Conserving Main Storage 625 

Appendix I: Macro Instructions for Time-Sharing Support 627 

Appendix!: Concentrating and Deconcentrating Messages 653 

Glossary 685 

Index 695 



Figures 



Figure 1 . Deciding Whether a TERMINAL Macro Should 

be Coded for a Switched Line 40 

Figure 2. Two Buffers Assigned to a Line Group; KEYLEN=60 

and BUFSIZE=I20 64 

Figure 3. Unit Allocation when Main-Storage Queuing (with or 

without Backup on Disk) is Specified 67 

Figure 4. Unit Allocation when Disk-Only Queuing is 

Specified 67 

Figure 5. 706-byte Data Movement Resulting from Size 

Disparity between Input and Output Buffers 76 

Figure 6. Relative Record Numbers of Disk Message Queues 

Data Set Assigned Across Three Volumes 90 

Figure 7. Reorganizing a Reusable Data Set 93 

Figures. Sample MCP Activation and Deactivation Section 135 

Figure 9. Sample Format for an Incoming Message 138 

Figure 10. Sample Format for an Outgoing Message 140 

Figure 11. Message Handler Subgroups and Macros 144 

Figure 12. Scan Pointer Movement 151 

Figure 13. Flow of Logical Message Formed by Blocking 

Two Physical Transmissions 156 

Figure 14. Flow of Logical Message Formed by Deblocking 

A Physical Transmission 158 

Figure 15. Message Flow for a Switched Message 165 

Figure 16. Message Flow for a Message that is Processed by 

an Application Program 166 

Figure 17. Flow of a Two-Segment Message with a Single-Buffer 

Header through an MH 168 

Figure 1 8. Flow of a Two-Segment Message with a Multiple-Buffer 

Header through an MH 170 

Figure 19. Activation of a Closed, User-Written Subroutine 178 

Figure 20. Deletion of Data from a Message Segment, followed by 

Contraction of the Segment; KEYLEN=60 and BUFSIZE= 120 264 

Figure 21. Example of Using the MSGTYPE Macro Instruction 278 

Figure 22. Example of Using the PATH Macro Instruction to Vary 

MH Processing 285 

Figure 23. Example of Using the PRIORITY Macro Instruction 289 

Figure 24. Example of Inserting Line Address 296 

Figure 25. Sample Message-Switching Program (5 parts) 323 

Figure 26. Sample Inquiry/Response Program (9parts) 330 

Figure 27. Sample Checkpoint Coordination Program ( 1 1 parts) 341 

Figure 28. Interface between the Application Program and the TVICP 357 

Figure 29. Relative Positions of Optional Fields in the Work 

Area 387 

Figure 30. Effect of a Work-Unit's Type and Format on the Way 

in which TCAM Determines its Size 394 

Figure 31. Example of Multiple-Wait Capability 412 

Figure 32. Terminal Table DSECT for Single, Line, and Group 

Entries 417 

Figure 33. Sample Invitation List Containing Three Entries 421 

Figure 34. Example of Using the CKREQ Macro Instruction for 

Checkpoint Coordination 448 

Figure 35. Operator Commands Classified by Areas Affected 492 

Figure 36. Equations for Determining the Size of the Checkpoint 

Data Set (2 parts) 511 

Figure 37. Information Flow for Message Logging 516 

Figure 38. Coding Requirements for Using TCAM Debugging Aids 531 

Figure 39. Device Configurations Supported by TCAM (3 parts) 540 

Figure 40. Sample JCL for lEDQXA Utility 543 

Figure 41 . Example of Using the lEBUPDTE Utility (prior to IPL) 

for Placing a List in SYSl.PARMLIB 552 

Figure 42. TCAM Internal and Device Codes (4 parts) 561 

Figure 43. IBM S/360 Internal Code (EBCDIC) 569 

Figure 44. USASCII Code 570 



xm 



Figure 45. Hexadecimal Equivalents for 6-bit Transcode 571 

Figure 46. Line Code for IBM 1030 Data Collection System 572 

Figure 47. Line Code for IBM 1050 Data Communication System 573 

Figure 48. Line Code for IBM 1060 Data Communication System 574 

Figure 49. Line Codes for IBM 2260 (Remote)/2265 Display Complexes 

and IBM 1053 Printer (2 parts) 575 

Figure 50. Line Code for IBM 2740 Communication Terminal 577 

Figure 51. Hexadecimal Equivalents for IBM 2741 (BCD) Communication 

Terminal 578 

Figure 52. Line Code (EBCD) for IBM 2741 Communication Terminal 579 

Figure 53. Line Code (Correspondence) for IBM 2741 Communication 

Terminal 580 

Figure 54. Line Code for AT&T 83B3 and WU 1 r5A Terminals 581 

Figure 55. Line Codes for AT&T TWX Terminals 582 

Figure 56. Line Code for IBM World Trade Telegraph ITA2 583 

Figure 57. Line Code for IBM World Trade Telegraph ZSC3 584 

Figure 58. IBM 50 MDI Control Codes 617 

Figure 59. Required, Optional, and Invalid Features for TSO 

Terminals 634 

Figure 60. Message Flow for Incoming Concentrated Message 663 



Macro Directory 



CANCELMG— 210 
CHECK— 406 
CHECKPT— 212 
CKREQ— 446 
CLOSE 

Application Program — 380 

MCP— 134 
CODE— 213 
COMMBUF— 217 
COUNTER— 219 
CTBFORM— 672 
CUTOFF— 221 
DATETIME— 223 
DCB 

Checkpoint — 105 

Input — 361 

Line Group — 79 

Log— 107 

Message Queues — 102 

Output— 367 
ERRORMSG— 225 
FORWARD— 229 
GET— 396 
HOLD— 234 
ICHNG— 428 
ICOPY— 420 
INBLOCK— 199 
INBUF— 201 
INEND— 203 
INHDR— 200 
INITIATE— 238 
INMSG— 202 
INTRO— 113 
INVLIST— 11 
LOCK— 241 
LOCO PT— 244 
LOG— 245 
LOGTYPE— 51 
MCOUNT— 409 
MCPCLOSE— 381 
MHGET— 247 
MH PUT— 249 
MRELEASE— 431 
MSGEDIT— 252 
MSGFORM— 266 
MSGGEN— 269 



MSGLIMIT— 273 
MSGTYPE— 275 
OPEN 

Application Program — 378 

MCP— 127 
OPTION— 21 
ORIGIN— 280 
OUTBUF— 205 
OUTEND— 207 
OUTHDR— 204 
OUTMSG— 206 
PATH— 282 
PCB— 372 
POINT— 433 
PRIORITY— 286 
PUT— 398 
QACTION— 667 
QCOPY— 424 
QRESET— 443 
QSTART— 585 
READ— 400 
READY— 130 
REDIRECT— 290 
RETRY— 292 
SCREEN— 293 
SEQUENCE— 297 
SETEOF— 299 
SETEOM— 301 
SETSCAN— 304 
SLOWPOLL— 309 
STARTMH— 193 
TCHNG— 426 
TCOPY— 417 
TERMINAL— 25 
TERRSET— 311 
TGOTO— 665 
TLIST— 43 
TPDATE— 410 
TPEDIT— 613 
TPROCESS— 45 
TTABLE— 20 
TYPETABL— 313 
UNLOCK— 314 
WRITE— 403 



Operator Command Directory 



ACTVATED— 459 
ACTVBOTH— 460 
AUTOSTOP— 461 
AUTOSTRT— 462 
CPRIOPCL— 463 
DATOPFLD— 464 
DEBUG— 465 
DPRIOPCL— 467 
DSECOPCL— 467 
ENTERING— 468 
ERRECORD— 469 
GENPOLOFF— 471 
GENPOLON— 472 
GOTRACE— 472 
INACTVTD— 473 
INTERVAL— 474 
INTRCEPT— 474 



LNSTATUS— 475 
NOENTRNG— 476 
NOTRACE— 477 
NOTRAFIC— 478 
OPTFIELD— 480 
POLLDLAY— 481 
QSTATUS— 482 
RESMXMIT— 483 
RLNSTATN— 484 
STARTLINE— 484 
STATDISP— 485 
STOPLINE— 486 
STSTATUS— 487 
SUSPXMIT— 488 
SYSCLOSE— 489 
SYSINTVL— 490 



How To Use This Book 



This book is a reference manual and coding guide for the system programmer who 
must construct or modify a TCAM Message Control Program, or an appUcation 
programmer who must write a TCAM-compatible appUcation program. Familiari- 
ty with the overall concepts and structure of TCAM is assumed; a good way to 
achieve this familiarity is to read the TCAM Concepts and Facilities publication. 

The first seven chapters of the book are concerned with tasks you will encounter 
in constructing a TCAM Message Control Program (MCP), such as defining 
buffers, defining data sets, activating and deactivating an MCP, and actually 
putting an MCP together. The eighth chapter tells how to make your application 
programs compatible with a TCAM MCP. Following this is a chapter telling how 
to use auxiUary services provided by TCAM, such as the checkpoint/restart 
facility, the operator control capability, and the on-line test function. The final 
chapter contains information that might be useful in planning and setting up an 
actual teleprocessing system incorporating TCAM — including TCAM's machine 
and device requirements, a list of stations supported by TCAM, system-generation 
considerations specific to TCAM, and directions for Preformatting TCAM data 
sets residing on disk. 

Several appendixes containing special, helpful information for the system program- 
mer are located in the back of this publication. They include macro instruction 
formats, transmission-code charts, and aids for conversion from QTAM to 
TCAM. Of particular interest to the system programmer is the appendix on 
device-dependent considerations, which should be read before an MCP is coded. 
Throughout this publication, wherever a particular device dependency would 
appear, a reference is made to this appendix instead of Hsting the individual 
consideration. Appendix I contains macro descriptions and coding considerations 
for the system programmer who incorporates the Time Sharing Option (TSO) in 
his system; it is intended primarily for the programmer who designs his own TSO 
message-handling facilities rather than use an IBM-supplied message-handling 
routine for TSO applications. Appendix J contains macro descriptions and coding 
considerations for the system programmer who incorporates a message concen- 
trating device in his teleprocessing network. 

As a first step in famiharizing yourself with this book, look over the table of 
contents. This book is organized around user tasks, rather than around macros. In 
defining buffers or terminal- and line-control areas, you must code operands of 
several macros. If the book were organized around the macros, you would have to 
look at each operand of each macro to determine which operands pertained to 
buffer definition, which to terminal- and line-control-area definition, which to 
incorporating a checkpoint facility, etc. Because the book is organized around 
tasks, rather than macros, you are saved much of this work. For example, the 
chapter Defining Buffers contains a checklist of those TCAM macro operands 
having to do with buffer definition. One of the macros mentioned in this checklist 
happens to be located in the chapter Activating and Deactivating the Message 
Control Program , another is in the chapter Defining the MCP Data Sets , a 
third in the chapter Defining Terminal and Line Control Areas . By discussing 
together those operands having to do with buffers in a section titled Defining 
Buffers , the book saves you the trouble of haying to locate these operands your- 
self when you design and specify your buffers. 



How to Use This Book 1 



In addition, the task-oriented organization facilitates retrieval of information: to 
locate information on TCAM's reusable disk queuing scheme you need only relate 
reusable disk queuing to the task of defining the MCP data sets and look in the 
table of contents under the chapter-heading Defining the MCP Data Sets . 
Similarly, to locate information on TCAM's checkpoint facility, you need only 
remember that this is a service facility and look under the chapter-heading Using 
TCAM Service Facilities . Of course, this method of retrieving information by 
relating it to tasks will work only if you are aware of the tasks we discuss. Each 
chapter heading shown in the table of contents is the name of one such task. 

References to other books appear in this publication in a shortened form; their 
complete titles and order numbers appear in a table in the Preface . 



2 OS/MFT and OS/MVT TCAM Programmer s Guide 



Writing the Message Control Program 



What the Message Control Program Is 

The Message Control Program (MCP) is a set of routines that identify the telepro- 
cessing network to the IBM System/ 3 60 operating system, estabUsh line control 
required for the various kinds of stations and modes of connection, and control 
the handling and routing of messages in accordance with the user's requirements. 
Every teleprocessing system operated under TCAM requires one MCP. 

The MCP serves as an intermediary between the remote stations, and between a 
remote station and an appUcation program. Device-dependent input/output 
operations are performed by TCAM routines in the MCP, based on station and 
Une configurations of the system as specified in the operands of TCAM macro 
instructions in the MCP. 

An MCP is coded using a group of TCAM macro instructions. Coding require- 
ments and restrictions for a TCAM macro are identical to those for any other 
assembler language macro instruction. Assembler language conventions for 
coding continuations, comments, symbols, and the length, number, and format of 
operands apply to all TCAM macros. 



Functions of the MCP 



Depending on the requirements of the user, the TCAM MCP might perform any 
of the following specific functions: 

• Enable and disable communication lines. 

• Invite terminals to transmit messages. 

• Receive messages from terminals. 

• Dynamically assign buffers to incoming messages. 

• Handle messages on the basis of user-specified priorities. 

• Perform message-editing functions for incoming messages. Among such 
functions are the following: translating from the transmission-code to 
EBCDIC code; deleting line-control characters; inserting time-received and 
date-received information in the message header; recording the message on a 
secondary storage medium (logging); inserting or removing user-specified data 
in the header; maintaining a count of the number of messages received from 
each station. 

• Determine the appropriate destination queue for a message and route the 
message to that queue. 

• Queue the message on the appropriate destination queue. 

• Place response messages generated by application programs on queues for 
subsequent transmission. 

• Retrieve messages from destination queues and prepare them for transmission 
to stations. 

• Perform message-editing functions for outgoing messages. Among such 
functions are the following: placing time-sent and date-sent information in the 
message header; placing an output sequence number in the header; inserting or 
removing user-specified data in the header; logging the outgoing message on a 
secondary storage device; maintaining a count of the number of messages sent 
to each terminal; inserting line-control characters; translating the message from 
EBCDIC code to the appropriate transmission code. 



Writing the Message Control Program 3 



• Take periodic checkpoints of the system. 

• Provide operator-to-system communications through system control terminals. 

• Initiate corrective action when an error or unusual condition is detected. 

• Cancel incoming messages containing errors. 

• Reroute messages with erroneous header information to a special queue. 

• Transmit error messages. 

User Tasks in Writing the MCP 

As a system programmer concerned with writing a Message Control Program, you 
will be confronted with five basic tasks: 

1. Defining the various terminal and line control areas used by the MCP; 

2. Defining the buffers used by the MCP for handling, queuing, and transferring 
message segments; 

3. Defining the data sets referred to by the MCP; 

4. Activating and deactivating the MCP data sets; 

5. Defining the Message Handlers, the sets of routines that examine and process 
control information in message headers, prepare message segments for forward- 
ing to their destination, and route messages to their proper destinations. 

In the next five chapters, we shall consider each of these tasks in detail. 



4 OS/MFT and OS/MVT TCAM Programmer's Guide 



Defining Terminal and Line Control Areas 



In constructing the Message Control Program, the user must provide control 
information that identifies the remote stations, specifies their characteristics to the 
system, and tells how they are to be handled by TCAM. This chapter describes 
how this information is specified. 



Terminology 



In the following discussion, the word computer refers to the central computer in 
the TCAM system; this is the computer that contains the Message Control 
Program. Remote terminals, as well as remote computers, are referred to as 
stations . 



Line Control 



A nonswitched line (also known as a leased or dedicated line) is one over which 
connections between the computer and remote stations are continuously estab- 
lished. A switched line (also known as a dial line) is one over which a direct 
physical connection between the computer and a remote station must be estab- 
lished by dialing for data transmission to occur. 

A point-to-point line connects a single remote station to the computer. Switched 
lines are considered to be point-to-point. A multipoint line connects two or more 
stations to the computer. For lines to Binary Synchronous Communications 
(BSC) stations, a Hne to one station is considered to be multipoint if multipoint 
ESC data-Hnk control is used on the line. 

A contention line is one over which the computer and a station may vie for use of 
the Une. Either the computer or a station may "seize" the line, thereby preventing 
its use by another device on the Une until after the device that gained control of 
the line has transmitted its messages and relinquished control. All TCAM- 
supported stations not assigned poUing or addressing characters, except BSC dial 
lines, are considered to be contention stations. A non-contention line is one for 
which the computer, using certain user-specified information, determines which 
station is permitted to enter or accept messages at any particular time. 

The computer sends a message to a station and receives a message from a station; 
sending and receiving are functions of the computer. 

A station enters a message to be transmitted to the computer and accepts a 
message transmitted to it from the computer; entering and accepting are functions 
of a station. 



Just as a computing system, with its variety of peripheral input/output equipment, 
requires some means to coordinate the functioning of the various parts, the variety 
of I/O equipment comprising a teleprocessing system requires a discipline to 
effectively manage the flow of message traffic. A significant difference should be 
noted, however. In a conventional computing system, the various I/O devices are 
at the service of the programmer; the requirements of his program and the charac- 
teristics of the data to be processed largely determine which input and output 
devices are to be activated and when. Moreover, the I/O devices are within reach 
of the computer operator; he can intervene when a device malfunctions to correct 
the condition or to assign a different device. In a teleprocessing system, on the 
other hand, the central computer receives data at random from remote stations, 



Defining Terminal and Line Control Areas 5 



and the operator at the central computer cannot exercise any direct control over 
remote stations. He cannot, for example, correct a malfunctioning device at a 
remote station. 

A further distinction between a computing system and a teleprocessing system lies 
in the handling of errors in data. With current techniques for transmitting data 
over long distances, errors can be introduced into message data by unavoidable 
transient Une conditions, such as crosstalk and Ughtning strikes. Transmission 
errors occur much less often in a computing system. A discipline for a telepro- 
cessing system must detect transmission errors and, when possible, correct them 
(as by retransmitting the message containing the errors). If the error cannot be 
recovered from, its occurrence must be indicated to the user program so that 
appropriate action can be taken. 

The scheme of operating procedures and signals by which a teleprocessing system 
is managed is called line control (for binary synchronous communications, the 
term data-link control is often used). A line control scheme must consider the 
functional characteristics and capabilities of the equipment and communication 
lines comprising the system, as well as the operational requirements of the system. 
Some specific factors that line control must consider are: How is contact to be 
estabhshed between a sending and a receiving station? How is a message to be 
directed to a specific station on a multistation line? What if two stations try to 
send at the same time? What should be done if a station fails to respond to a 
message? 

Line control can be classified in two ways. The first way is by the transmission 
technique (start-stop or BSC) used for the Une under consideration. A set of 
control characters and rules for their use is associated with each of these tech- 
niques to effect the needed functions. Some of the control characters are used for ' 
both start-stop and BSC transmission, while others are pecuHar to one or the other 
of the transmission techniques. For a discussion of these transmission techniques, 
see the TCAM Concepts and Facilities publication. 

The second way in which Une control can be classified is by the communication 
line configuration with which it is used. For example, line control for a switched 
Une differs from that for a nonswitched line in the way in which initial contact is 
made. 

While a given line-control scheme is identified in terms of transmission technique 
and line configuration, differences may arise in the stations to be controlled and 
by the presence or absence of certain features in the stations. For example, a 
given Une-control scheme may include the control characters needed to indicate a 
transmission error and to request automatic retransmission, but some station 
equipment using that line-control scheme may not be capable of error checking or 
automatic retransmission. Generally speaking, aU stations connected to a given 
Une must be designed to use the same Une-control scheme, and where a certain 
capability is provided by some stations but not by others, the capabiUty cannot be 
used. 

It is not necessary for the TCAM programmer to specify the Une-control scheme 

to be used for a given line; this information is provided impUcitly at system 

generation time, at assembly time in the DCB macro instruction for the line group 

of which the given Une is a member, and in the TERMINAL macro instructions 

for the stations on the line. The programmer must, however, have a general I 

understanding of Une-control concepts to correctly structure that portion of his 



6 OS/MFT and OS/MVT TCAM Programmer's Guide 



program involved in message transmission, and to decide intelligently how to deal 
with line-control characters in his message. 

For start-stop stations, the line-control characters recognized by TCAM are EOA 
and BOB. For BSC stations, the line-control characters recognized by TCAM are 
STX, ETB, and ETX. TCAM removes all of these line-control characters except 
the EOT from incoming messages if the LC= operand of the STARTMH macro is 
coded LC=OUT, and leaves them in incoming messages if the LC= operand is 
coded LC=IN (except that line-control characters are always removed from 
incoming messages in transparent mode). TCAM inserts line-control characters 
into outgoing messages if the MSGFORM macro is coded in the outheader 
subgroup of the Message Handler (MH) handling the outgoing message. 

If the station that enters the message and the stations that are to accept it are 
either all similar start-stop or all BSC, and if the user does not wish to change the 
size of physical blocks of data in the message (if the message is divided into such 
blocks by EOB or ETB line-control characters), then line-control characters may 
be left in the message. If the originating and destination stations use different line 
codes, then the CODE macro must be issued at appropriate places in the MH so 
that TCAM can translate the message from the Une code for the originating 
station to EBCDIC, then to the line code for the destination station. TCAM's 
translation tables are set up so that Une-control characters for an originating 
station using one Une code are translated into satisfactory characters in the line 
code for the destination station, provided that both the originating and the desti- 
nation stations are either similar start-stop or BSC devices. 

If incoming data is being blocked to form logical messages, the LC=OUT operand 
of STARTMH should be specified to remove line-control characters, and the 
MSGEDIT functional MH macro should be used to remove EOT characters 
included in the message. 

Line control may be left in a message that is processed by a TCAM appUcation 
program; of course, the user code in the application program will have to take 
account of line-control characters if they are left in the message. 

For a message sent between a start-stop and a BSC station, whether directly or 
through an appUcation program, the conversion of Une-control characters by 
TCAM's translation tables is less likely to be satisfactory. Figure 40 in Appendix 
D is a chart showing the line-code equivalents of EBCDIC graphic and control 
characters for each station supported by TCAM. This chart may be used to 
determine the character to which TCAM's translation tables wiU translate an 
incoming character. For example, an incoming ETB character from a BSC station 
using EBCDIC line code, if left in the message, will be translated to an EOB 
character if TCAM's 1050 translation table is used to translate the message from 
EBCDIC to 1050 line code. (The translation table to be used by TCAM is 
specified by means of the TRANS= operand of the line group DCB macro, while 
the CODE macro causes translation to be performed and may be used to override 
the translation table specified in the DCB.) 

If the user switching messages between stations having different Une codes is 
satisfied with the equivalent characters provided by TCAM's translation tables, 
and if he is satisfied with the size of the physical blocks (if any) in his message, he 
may leave line-control characters in his message; otherwise, he should remove 
line-control characters from the incoming message by specifying LC=OUT in his 
STARTMH macro, and insert appropriate Une-control characters in his outgoing 



Defining Terminal and Line Control Areas 7 



message by coding a MSGFORM macro in the outgoing group of the Message 
Handler handhng the message. 

Operands of MSGFORM permit the user to specify fixed outgoing blocking 
factors, some of which may be overridden on a terminal-by-terminal basis. They 
also permit him to specify variable-length blocking for outgoing messages. The 
user specifies the number of subblocks for each block and the character that 
delimits each subblock. The user who wishes to specify physical blocks of data 
that differ in length within the same message may do so by inserting the appropri- 
ate line-control characters in his outgoing message by coding the MSGEDIT 
macro. 

TCAM does not consider the ITB control character in BSC to be a line-control 
character and does not remove it from incoming messages when LC=OUT is 
coded in the STARTMH macro. The user may delete ITB characters by coding 
the MSGFORM macro in the inblock subgroup. The MSGEDIT macro may be 
used to remove and insert ITB characters, and the BLOCK= operand of the 
MSGFORM macro may be used to specify a fixed interval at which ITB charac- 
ters are to be inserted by TCAM into outgoing messages. 

For BSC stations, another transmission variable involves the treatment of hne- 
control characters in a message. BSC messages may be transmitted in transparent 
mode or in nontransparent mode. 

The transparent mode is a type of BSC transmission in which message segments 
may include certain normally restricted data-Unk control characters, which are 
transmitted as ordinary data and not as functional control characters; the only 
functional data-Unk control characters transmitted when a message is in transpar- 
ent mode are those preceded by a DLE data-link character. Transparent mode is 
useful in transmitting messages containing binary data, fixed- and floating-point 
data, packed decimal digits, source programs, and object programs, because with 
such messages the binary structure of a character may be the same as that for a 
data-link control character. 

When a message in transparent mode arrives at the computer, TCAM automatical- 
ly removes the two initial line-control characters and all functional ETB and ETX 
control characters. All DLE STX sequences are also removed, except those 
immediately following an ITB. These characters are removed whether or not 
LC=OUT is coded in the STARTMH macro. If the user wishes to remove the 
ITB, DLE, STX sequence, he may specify a MSGFORM macro in the inblock 
subgroup of his Message Handler. If the user wishes to place a message in trans- 
parent mode before sending it to a BSC station, he issues a MSGFORM macro 
specifying SENDTRP= YES in the outheader subgroup handUng messages for that 
station. 

In nontransparent mode , all line-control characters are treated as such, and line 
control is handled as it is for start-stop stations. 

In deciding whether to remove and insert line-control characters, and whether 
messages to BSC stations are to be in transparent mode, the TCAM programmer 
is concerned with Une control at the character level. On a more general basis, he 
must make decisions regarding those line-control functions used by TCAM to 
establish contact between the computer and remote stations, and those functions 
used to maintain an orderly flow of message traffic. The rest of this chapter 
contains information to help him make and implement these decisions. 



8 OS/MFT and OS/MVT TCAM Programmer's Guide 



Establishing Contact 



With TCAM, contact for the purpose of message transmission may be estabUshed 
in several ways, depending upon the line configuration and the stations involved. 
Contact is always established under the control of the central computer, which 
performs (in the channel) a number of ''set-up" or preparatory operations, which 
are followed by either a Read or a Write operation on the line (except when the 
set-up operations determine that the remote station is not free to enter or accept 
data, in which case no message transmission occurs). 

In this pubUcation, when contact is established for the purpose of receiving data 
from a station, the process is called invitation ; when contact precedes the sending 
of data to a station, the process of establishing contact is called selection . Selec- 
tion is performed when the central computer has a message to send to a station; 
invitation is performed to give a station the opportunity to enter a message if it 
has one ready (in some cases of invitation, the station initiates contact with the 
computer to enter a message and the computer completes the invitation process). 



Invitation 



There are two forms of invitation: contention (with or without identification 
sequence exchange) and polling . 

In a TCAM system either the computer or a station on a point-to-point conten- 
tion line can *'bid" for use of the line so that it can send a message to another 
device. In some configurations, it is possible for both the computer and the 
station to simultaneously bid for the line; when this happens, the computer and 
the station are said to contend with each other (hence the name contention line ). 

For contention stations, invitation by TCAM means that TCAM gives the station 
an opportunity to enter data, that is, TCAM ''Ustens" on the line for a signal from 
the station indicating that the station wishes to enter a message. 

The alternative to contention involves having the central computer periodically 
examine each active entry in an invitation Ust (discussed below) of remote stations 
and invite each station to enter any input messages it has ready. Each station in 
the list has a unique identifier, usually consisting of one or two characters that 
cause that station, and no other, to respond. The process of contacting each 
remote station in this manner is called polling , and the station identifiers are 
called polling characters . Often, the first polUng character identifies the station 
and the second identifies a particular component of the station. 

For polled nonswitched lines, TCAM commences invitation by polling the first 
station Usted in the invitation list for the line. (If the line is point-to-point, the 
first will be the only station on it, and the invitation Ust for the Une need contain 
only one entry.) TCAM uses polling characters unique to each station to deter- 
mine, station by station, whether there is a message to send. If a response is 
negative, or if there is no response (that is, if the station is down), the polling 
characters for the next station Usted are sent; this process is repeated until a 
station responds positively by entering a message. When there is no response, a 
timeout wiU occur on the read response to polling. TCAM error recovery (ERP) 
modules wiU gain control to retry the polling operation. This time-out is consid- 
ered a temporary error, and TCAM will retry until either a response is received or 
a STOPLINE is performed. To prevent system degradation due to high ERP 
activity TCAM should not be started on a Une for which a terminal wiU f aU to 



Defining Terminal and Line Control Areas 9 



respond. Such a station is permitted to enter any messages it may have ready for 
the computer and may be sent any messages that are queued for it (see 
Transmission Priority in this chapter for a discussion of when sending to a station 
may occur relative to receiving). After all messages are entered, the computer 
interrogates the next station in the invitation list. After all the active stations in 
an invitation list for a given polled line have been invited to enter a message, a 
delay (equal to the number of seconds specified in the INTVL= operand of the 
DCB macro for the line group) may be observed to allow for sending before 
polling is restarted at the beginning of the list; if this operand is omitted, no delay 
occurs. The polling interval reduces unproductive polling on lines that are not used 
continually. 

For nonswitched polled lines, the computer initiates contact with the stations. 
However, for switched lines the station may initiate the contact by successfully 
dialing the computer. The polling function in this case consists only of sending the 
polling characters to the station that initiates the contact. The station responds by 
entering one or more messages. The computer sends the polling characters after 
each message is received. 

It is possible for the computer to dial some types of polled stations on switched 
lines. The user may specify computer-initiated contact by coding certain operands 
of the TERMINAL macro, discussed below. In this case, the polling characters 
for the station are sent once contact has been established and all messages queued 
for the station have been transmitted. 

Constructing the Invitation List 

A TCAM system maintains control of invitation by having an invitation hst, 

created by an INVLIST macro instruction, for each line. (. 



1 OS/MFT and OS/M VT TCAM Programmer's Guide 



symbol 



INVLIST 



The INVLIST macro 

• generates the invitation list for a line; 

• specifies active and inactive invitation list entries; 

• is required for each line in the system (though the same INVLIST macro may 
be sufficient for more than one output-only line); 

• is specified following the macros defining the terminal table. 

• indicates whether TCAM is the master or slave in a contention situation on a 
BSC device. 

One INVLIST macro must be issued for each line in the system, with the excep- 
tion of output-only lines to stations that do not use invitation sequences; a single 
INVLIST macro is sufficient for all such output-only Unes. The names of all 
INVLIST macros for the lines in a line group must be specified, by ascending 
relative line number, in the INVLIST = operand of the DCB macro for the line 
group. 

For each station on a line, the INVLIST macro creates an invitation list entry that 
contains the invitation characters for the station (the polling characters for polled 
stations, or the identification sequence assigned to TWX and switched BSC 
stations using such a sequence). See Appendix G. Device-Dependent 
Considerations , for particular invitation list specifications for the: 

• 2260 Display Stations, both local and remote; 

• 2740 Communications Terminal with the Station Control or Station Control 
and Checking feature; 

• BSC terminals; 

• 2740 Communications Terminal with the Transmit Control or Transmit Con- 
trol and Checking feature; 

• TWX terminals; 

• 7770 Audio Response Unit, Model 3. 

No invitation characters are present in entries for contention terminals not 
assigned identification sequences. 

INVLIST has the following format: 



Name 


Operation 


Operands 


symbol 


INVLIST 


ORDER=(entry,...)[,EOT=hexchars] 
[,CPUID=addr] l,MASTER= YES] 

NO 



Function: Specifies the name of the macro and of the invitation list for the line. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: This name must be the same as the name specified by the INVLIST= 

operand of the DCB macro for the line group containing this line. 



Defining Terminal and Line Control Areas 1 1 



ORDER= (entry,...) 



EOT=hex chars 



CPUID=addr 



Function: Specifies the invitation list entries for the Hne. 

Default: None. For all output-only lines to stations having no ID sequence 

assigned to them, specification optional. For all other cases, this operand must be 

specified. 

Format: The exact manner in which each entry is coded is described below. A 

maximum of 200 entries may be coded. 

Notes: For polled lines, there must be at least one entry for each station that can 

enter messages on the line. Entries are specified in the order in which the stations 

are to be invited to send messages. 



Function: Specifies the EOT line-control character for the stations on this line. 

Default: None. For Hnes to multipoint BSC stations, this operand must be 

specified. For all other cases, this operand must not be specified. 

Format: A single hexadecimal character, unframed, in the transmission-code 

representation. 

Notes: Appropriate EOT characters are as follows: 

. for EBCDIC: 37 

. for ASCII: 04 

• for 6-bit Transcode: IE 

Example: 

For a hne to multipoint BSC stations using ASCII as their transmission-code, this 
operand would be coded as follows: 

EOT=04 

where 04 is the ASCII transmission-code representation of the EOT control 
character, in hexadecimal notation. 



Function: Specifies the name of a field containing the ID sequence assigned to the 

computer. 

Default: None. For switched lines to stations using ID sequences, when the 

computer is expected to exchange ID sequences with stations on the line when 

calls are made, this operand must be specified. For all other cases, specification 

optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The field named by addr should consist of a length byte, specifying in 

binary form the number of characters in the computer ID sequence, followed by 

the ID sequence itself in line code. For more information on ID sequences, see 

Switched Line to Stations Using ID Sequences below. This operand also 

specifies the invitation message for audio terminals. 

Example: 

For a switched line to stations using ID sequences and EBCDIC line code, this 
operand might be coded as follows: 

CPUID=CPUNAME 



Somewhere within the same area of addressabihty in the MCP the following field 
might be defined: 



CPUNAME 



DC X'04' 

DC X'D5D6D3C1 ' 



1 2 OS/MFT and OS/M VT TCAM Programmer's Guide 



MASTER^ \ YES 
NO 



Here, X'04' is the hexadecimal number of bytes in the rest of the field, while 
X'D5D6D3Cr is the EBCDIC character sequence NOLA in hexadecimal nota- 
tion. 



Function: Specifies whether TCAM assumes the role of master or slave in point- 
to-point, nonswitched contention situations. See Appendix G. Device-Dependent 
Considerations for Binary Synchronous Communication (BSC) Terminals. 
Default: NO 

Format: MASTER=YES or MASTER=NO 

Notes: MASTER=YES indicates that TCAM will continue to bid for the line in a 
contention situation until the contention is resolved. MASTER=NO indicates 
that TCAM will discontinue bidding for the line in a contention situation. This is 
normal operation for point-to-point, nonswitched, contention stations as de- 
scribed in TCAM Send and Receive Operations on a BSC Line in Appendix 
G. 

Each entry specified as a suboperand of the ORDER= operand consists of a 
station or line name, an indicator that determines whether the station represented 
by the entry is initially capable of entering messages, and a sequence of invitation 
characters. This sequence of invitation characters is limited to 46 alphameric 
symbols (23 hexadecimal bytes). 

The station name must be the name of the TERMINAL macro for the station 
being entered in the list. 

The indicators to distinquish active from inactive entries are as follows: 

+ indicates that the station represented by the entry is initially activated for 
entering messages. 

- indicates that the station represented by the entry is not initially activated 
for entering messages. 

Entries may be both activated or deactivated for entering, accepting, or both 
entering and accepting, by means of various operator commands or by an ICHNG 
macro issued in an application program. When poUing is used as the method of 
invitation, only stations that are activated for entering are polled. 

Following the indicator in an entry are the invitation characters for the station. 
These will be either polling characters or an identification sequence. Invitation 
characters are generally assigned to a station when it is installed. For information 
on whether a particular station can be assigned identification or polling characters, 
consult the component description SRL for that type of station. Invitation 
characters are specified in transmission-code representations converted to hexade- 
cimal notation. (For conversion tables, see Appendix D .) Each group of invita- 
tion characters in a Ust must be of the same length. 

An invitation list entry might be coded as follows: 

NYC+E40D 

Here NYC is the name of an IBM 1050 terminal in New York City, + indicates 
that this entry is active for entering messages, and E40D is the IBM 1050 



Defining Terminal and Line Control Areas 1 3 



transmission-code representation of the polling characters B6 in hexadecimal 
notation. 

Because one operand of a macro is limited to 255 characters, TCAM provides a 
facihty to specify additional INVLIST entries if necessary. A comma placed as 
the last character of the last entry field; that is, 

INVLIST ORDER=( entry, entry, . . .entry, ) 

indicates a continuation of the macro. The next source statement would then be 
coded 

INVLIST ORDER=( entry, entry, . . . ) 

There is no limit (other than the maximum of 200 entries that may be specified) 
on the number of continuation statements used. 

The exact manner in which the INVLIST macro is coded depends upon the line 
configuration and upon station features. The following paragraphs describe the 
possible ways in which INVLIST may be coded. 

Nonswitched point-to-point or multipoint lines to stations using polling characters 
Issue one INVLIST macro for each such line, and code at least one entry for each 
station (active and inactive) on the Hne. Each entry should include the terminal 
name, the active or inactive entry indicator, and the poUing characters assigned to 
the terminal. If a terminal is to be polled more than once in one pass through the 
invitation Ust, specify more than one entry for this terminal — the terminal will be 
polled once for each active entry specified. To poll a specific component o| a 
terminal, specify the second polUng character, which identifies that component. 

Example 1 : 

The following INVLIST macro creates the required invitation Ust for a non- 
switched multipoint line having three IBM 1050s as terminals. 

LIST1 INVLIST ORDER=(NYC+E40D,BOS+E20D,NYC+E40D, 

PHI-E715 ) 

TCAM uses the invitation Hst created by this macro to poll the IBM 1050 termi- 
nals located in New York City (NYC), Boston (BOS), and (again) New York 
City, in that order. The New York City terminal is polled twice as often as the 
Boston terminal. The Philadelphia terminal (PHI) is inactive until activated by the 
operator control facility or by an ICHNG macro issued in an appHcation program. 
E40D, E20D, and E715 are the IBM 1050 transmission-code representations of 
the polling characters B6, A6, and CO, respectively, in hexadecimal notation. + 
means the terminal is initially active; - means the terminal is initially inactive. 

Example 2: 

The following INVLIST macro creates the invitation Ust for a nonswitched 
multipoint line having one BSC IBM 2780 and one BSC IBM 1 130, using the 
Auto Poll hardware feature. 

LIST2 INVLIST ORDER=( BALH-C2F62D , DET+32C42D ) , 

EOT=37 



1 4 OS/MFT and OS/M VT TCAM Programmer's Guide 



TCAM uses the invitation list created by this macro to autopoU an IBM 2780 
located in Baltimore (BAL) and an IBM 1 130 located in Detroit (DET), in that 
order. The transmission-code for the terminals being autopoUed is EBCDIC; the 
C2F6 and C4 are the hexadecimal-notation form of the EBCDIC representation 
of the polling characters B6 and D, respectively. The 2D ending each entry is the 
hexadecimal-notation form of the EBCDIC representation of the ENQ line- 
control character, which must be included with all BSC poUing sequences. The 32 
in the Detroit entry is the hexadecimal-notation form of the EBCDIC SYN 
character, used to pad the DET polling sequence to the length of the BAL se- 
quence. The EOT= operand presents the hexadecimal form of the EBCDIC EOT 
character; it must follow all entries in an INVLIST macro for autopoUed terminals 
using EBCDIC transmission code. 

Switched lines to terminals using polling characters 

Issue one INVLIST macro for each such line. Polling characters for all polled 
terminals assigned to a switched line (by means of each terminal's TERMINAL 
macro, described below) must be identical. Since all terminals assigned to the 
same line have the same polUng characters, it is necessary to code only one 
representative entry as the operand of the INVLIST macro for a line; this entry 
names any one of the terminals assigned to the Une, and gives the poUing charac- 
ters for all terminals assigned to the line. A + should be coded for each entry. If 
a TERMINAL macro with the operand UTERM= YES is issued for the line, code 
the name of that TERMINAL macro, rather than the name of a terminal, in the 
representative entry. 

Example: 

The following INVLIST macro creates the invitation list for a switched line having 
three polled IBM 1050 terminals (NYC, BOS, and PHI) assigned to it. 

LISTS INVLIST ORDER=( NYC+E40D ) 

Whenever one of the three terminals calls in (or is called), TCAM uses the poUing 
characters represented in hexadecimal notation by E40D to invite it to enter a 
message. E40D is the IBM 1050 transmission-code representation of the polling 
characters B6, in hexadecimal notation. 

Note that only one of the three terminals is used to create the entry in the invita- 
tion list. If this entry were inactive (that is, if - rather than + were coded), none 
of the three terminals assigned to the Une could enter messages. 

Switched lines to stations using ID sequences 

Issue one INVLIST macro for each such line. Code one entry for each ID se- 
quence assigned to one or more stations on the line, and code the CPUID= 
operand if the computer is assigned an ID sequence. Each ID sequence is entered 
in its transmission-code representation, converted to hexadecimal notation. No 
framing characters or quotes are used. A -f should be coded for each entry. 

If each station assigned to a switched line has its own unique ID sequence, then 
one entry is coded for each station. Each entry consists of the station name, the 
active or inactive entry indicator, and the ID sequence assigned to the station. 
(See Example 1 below.) 

If two or more stations assigned to a switched Une share the same ID sequence, 
then one entry is coded for each different ID sequence assigned to a station or 
stations on the Une. If a TERMINAL macro specifying UTERM= YES is issued 



Defining Terminal and Line Control Areas 1 5 



for the line, then each entry consists of the name of the TERMINAL macro, the 
active/inactive entry indicator, and an ID sequence. If no such TERMINAL 
macro is issued, then each entry consists of the name of a representative station 
using the ID sequence mentioned in this entry, the active/inactive entry indicator, 
and an ID sequence. (See Example 2 below. For guidance on when to code a 
TERMINAL macro using UTERM= YES, see the discussion of the TERMINAL 
macro.) 

If a switched station calls in and enters an ID sequence, TCAM uses the ID 
sequence to estabUsh the origin of messages entered by the station. If a switched 
station (one that is assigned a non-unique ID sequence and that is represented by 
an invitation-Hst entry specifying the name of a TERMINAL macro coded for a 
Une) calls in and fails to identify itself by means of an origin field in a message 
header, the station will not receive any messages during the call because TCAM 
does not know whose messages to send unless there are messages queued for the 
line. If a switched station (one that is assigned a non-unique ID sequence and that 
is represented by an invitation-list entry specifying the name of a representative 
station using the ID sequence) calls in and fails to identify itself by an origin field 
in a message header, during the call the station receives those messages queued for 
the station named in the invitation-list entry, even if the calHng station and the 
station named in the invitation-list entry are two different stations. 

If a switched station calls in and enters an ID sequence, TCAM searches for the 
ID sequence in the invitation list associated with the Une over which the station 
called in. If the ID sequence is not found in an entry in the invitation Ust for this 
Une, TCAM conducts a search of the invitation Usts for any lines in this line group 
that have a higher relative line number than that assigned to the line over which 
the station called in. TCAM searches these invitation lists according to ascending 
relative line number until either the ID sequence is found in a Ust or the invitation 
Ust for the highest-numbered Une in the line group has been searched. If the ID 
sequence is found, TCAM assumes that the station associated with that ID 
sequence in the invitation Ust is the caUing station, and maintains the connection. 
If the ID sequence is not found, TCAM breaks the connection with the calling 
station, thereby freeing the line. 

Example 1: 

The following INVLIST macro creates the invitation Ust for a switched line having 
three IBM 2770 terminals (named NYC, BOS, PHI) assigned to it. Each of these 
terminals is assigned a unique ID sequence; that for NYC is AA, that for BOS is 
BB, while that for PHI is CC. PHI is not to be initially eligible for entering data. 
The computer is assigned the ID sequence POKl. The stations use EBCDIC line 
code. 

LIST4 INVLIST ORDER=( NYC+-C1 C1 , BOS+C2C2 , PHI-C3C3 ), 

CPUID=IDFIELD 

Here ClCl, C2C2, and C3C3 are the EBCDIC transmission-code representa- 
tions of the ID sequences AA, BB, and CC, respectively, in hexadecimal notation. 
Somewhere within the same area of addressability in the MCP the following field 
is defined: 

IDFIELD DC X»04' 

DC X*D7D6D2F1' 



1 6 OS/MFT and OS/MVT TCAM Programmer's Guide 



Here, 04 is the hexadecimal length of the rest of the field. D7D6D2F1 is the 
EBCDIC representation of the ID sequence POKl, in hexadecimal notation. 

Example 2: 

The following INVLIST macro creates the invitation Ust for a switched Une having 
six IBM 1 130 stations assigned to it. Three of these stations are assigned the ID 
sequence BATCH 1, while the remaining three are assigned the ID sequence 
BATCH2. The computer is assigned the ID sequence RAL. The stations use 
EBCDIC transmission code. A TERMINAL macro with UTERM=:=YES speci- 
fied, named RELLN3, has been issued for this line. 

LIST5 INVLIST ORDER=( RELLN3+C2C1 E3C3C8F1 , 

RELLN3+C2C1E3C3C8F2 ), 
CPUID=IDADDR 

Here, C2C1E3C3C8F1 and C2C1E3C3C8F2 are the EBCDIC transmission- 
code representations of the ID sequences BATCH 1 and BATCH2, respectively, in 
hexadecimal notation. Elsewhere in the MCP the following field is defined: 

IDADDR DC X'03' 

DC X'D9C1D3' 

Here, 03 is the hexadecimal length of the rest of the field. D9C1D3 is the 
EBCDIC transmission-code representation of the ID sequence RAL, in hexadeci- 
mal notation. 

Switched or nonswitched contention lines to terminals not assigned ID sequences 

If only one station is assigned to the line, include the station name and the active 
or inactive indicator in the entry portion of the macro. If more than one station is 
assigned to the line, include the name of a representative station and the active or 
inactive indicator in the entry portion of the macro. For IBM 2740 Basic and IBM 
2780 stations for which equal priority is specified in the line group DCB macro, 
include the station name and the active or inactive indicator in the entry portion of 
the macro. 

Example: 

The following INVLIST macro creates the invitation Ust for a nonswitched line to 
an IBM 2740 Basic terminal in New York City (NYC). 

LIST6 INVLIST ORDER=(NYC+) 

Output-only lines to stations having no ID sequences assigned to them 
Issue one INVLIST macro to serve all such Unes; the name of this macro should 
be specified in the INVLIST = operand of the DCB macro for each output-only 
line group. No operand is coded for this INVLIST macro. (Stations having ID 
sequences assigned to them must appear as entries in the INVLIST macro for their 
line, regardless of whether or not the line is output-only.) 

Example: 

The following INVLIST macro creates the invitation list for all output-only lines 
to stations having no ID sequences assigned to them. 

LIST7 INVLIST 



Defining Terminal and Line Control Areas 17 



Selection 

Selection is the process by which contact is established between the computer and 
a station for the purpose of transmitting data from the computer to the station. 

As is the case with invitation, there are basically two forms of selection. One of 
these is used with contention stations (which may or may not be equipped with a 
feature permitting identification sequence exchange), the other involves transmis- 
sion by the computer of addressing characters (similar to poUing characters) to a 
station preparatory to sending the station a message. Response to the transmis- 
sion of these characters indicates whether the terminal can accept the message. 

The contention form of selection is similar to the contention form of invitation, 
described above. When the computer has a message to send to a contention 
station, it waits until the line is free of traffic and then seizes it; once it has control 
of the line, the computer merely sends the message to the terminal. 

When addressing characters are used in selection, the selection process is closely 
related to the polling form of invitation, described above. That is, the flow of 
messages to and from a station is controlled by the computer according to an 
orderly scheme. The nature of this scheme is discussed in the section 
Maintaining Orderly Message Flow. Addressing characters are defined in the 
TERMINAL macro. 

Constructing the Terminal Table 

In selecting a station or application program, TCAM uses information provided by 
TCAM macros at assembly time and stored in control areas. The control areas 
used in selection all depend upon the terminal table. The terminal table consists 
of blocks of information about each station and appHcation program; each such 
block is called a terminal entry . 

There are eight types of terminal entries: 

• A single entry in the terminal table defines a single station. A single entry is 
created by a TERMINAL macro; one such entry must be created for each 
station in the system that is not defined by a group or Hne entry (see below). 

• A group entry represents a group of terminals on a hne that have a group 
addressing feature (whereby all terminals on a multipoint line recognize ad- 
dressing characters, but only one of the terminals responds); specification of a 
single set of addressing characters results in simultaneous transmission of a 
message to all terminals in the group. If a terminal that is a member of a group 
is also to be addressed individually, or is to be polled, it must be represented by 
a single entry as well. A group entry is defined by a TERMINAL macro and is 
for output only. 

• A component entry defines a component of a station that may be addressed 
individually — forexample, a card reader or a printer on an IBM 1050 station. If 
more than one component of a station may be addressed individually, a compo- 
nent entry may be required for each. A component entry is defined by a 
TERMINAL macro. 

• A line entry defines a switched line that is used for input or input/output 
operations. The line entry is used to supply device characteristics for stations 
that call in on a switched Une before they identify themselves (by the origin 
field in a message header, as checked by an ORIGIN macro in the Message 
Handler), and for stations that call in and never identify themselves. The entry 
is defined by a TERMINAL macro specifying UTERM=YES. 

• A distribution list entry contains a list of pointers to single, group, cascade, or 



1 8 OS/MFT and OS/M VT TCAM Programmer's Guide 



process entries. When a message or FORWARD macro contains the list name 
as its destination code, TCAM sends the message by separate transmissions to 
all stations indicated by the Ust. Each station on the list must have a corre- 
sponding single or group entry in the terminal table. A distribution list entry is 
defined by a TLIST macro. 

• A cascade list entry contains a list of pointers to single, group, or process 
entries. When a message or FORWARD macro contains the list name as its 
destination code, the message is queued to be sent to that single valid station or 
opened process entry in the Ust that has the least number of messages queued 
for it. A valid station is one that is capable of accepting a message, and that is 
on a line for which the line group data set has been opened. If more than one 
valid station has the sniallest number of messages queued, the message is 
queued for the first in the Ust. If no station is vaUd or if all queues are of the 
same length, the message is queued for the first station in the list. A cascade 
entry is defined by a TLIST macro. 

• A process entry represents an application program. One process entry must be 
defined for each queue to which an application program can issue a GET or 
READ and at least one must be defined for all PUTs or WRITEs from the same 
application program. One open input or output DCB in the application pro- 
gram is associated with each process entry. A process entry is defined by a 
TPROCESS macro. 

• A logtype entry represents a queue of complete messages for a logging medium. 
A logtype entry is defined by a LOGTYPE macro. 

The size, structure, and contents of the terminal table depend upon information 
provided by the user through the TTABLE, OPTION, TERMINAL, TLIST, 
TPROCESS, and LOGTYPE macro instructions. These macros are described in 
this chapter. 

Macro instructions defining the terminal table are coded as a group. For an 
example of a coding sequence for a terminal table, see the chapter Putting the 
MCP Together. 



Defining Terminal and Line Control Areas 19 



TTABLE 



symbol 



LAST = name 



lVlAXLEN=integer 



OLTERIVI=ii 



The TTABLE macro 

• defines the start of a terminal table; 

• names the last entry in the table; 

• is required as the first macro defining the terminal table; 

• is issued only once. 

An operand of TTABLE specifies the name of the last macro issued in the section 
of code defining the terminal table; thus, TTABLE defines the beginning and end 
of the terminal table coding section. The TTABLE macro must be followed 
immediately by the macros defining the terminal table. 

TTABLE has the following format: 



Name 


Operation 


Operands 


[symbol] 


TTABLE 


LAST = name[ ,M AXLEN = integer] 
[,OLTERM=n] 



Function: Specifies the name of the macro and the name of 

the terminal name table (an internal table associated with the terminal table). 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the last entry in the terminal table (that is, the 
name of the last TERMINAL, TLIST, or TPROCESS macro coded). 
Default: None. This operand must be specified. 
Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the number of characters in the name of the terminal table. 
Default: None. Specification optional. 
Format: An unframed decimal integer. 
Maximum: 8 

Notes: If this operand is omitted, the length of the last entry in the list is as- 
sumed. The operand is not necessary if the lengths of all terminal table entry 
names are the same, or if the last entry is the longest. 



Function: Specifies the number of dummy terminal name table entries to be 

allocated when using TOTE. See the description of TOTE in the section Using 

TCAM Service Facilities. 

Default: OLTERM=0. If zero dummy entries are allocated to TOTE, no remote 

station can be the control terminal or the alternate printer. 

Format: An unframed decimal integer. 

Maximum: 255 



20 OS/MFT and OS/MVT TCAM Programmer's Guide 



OPTION 



The OPTION macro 

• permits space to be reserved for an option field related to a station, component, 
line, or application program; 

• must be specified before any TERMINAL, TLIST, or TPROCESS macros; 

• is optional among the macros defining the terminal table. 

OPTION macros are issued as a group; in conjunction with the OPDATA= 
operands of the TERMINAL and TPROCESS macros they define the option 
table , a storage area containing option fields related to individual stations, compo- 
nents, lines, or application programs. Access to the option fields is gained by 
certain Message Handler routines that need source- or destination-related storage 
in order to perform their functions. Among the MH macros that invoke routines 
to gain access to the option fields are the following: STARTMH, INHDR, 
INBUF, INMSG, OUTHDR, OUTBUF, OUTMSG, COUNTER, ERRORMSG, 
FORWARD, LOCOPT, MSGLIMIT, PATH, and REDIRECT. To gain some 
insight into the function of option fields, the reader should turn to the individual 
discussions of these macros in the chapter De5/g«/>2g a Message Handler. 
User-written routines can also gain access to information in an option field. 

Taken together, the OPTION macros issued by a user define a complete set of 
option fields; all or part of this set may be assigned to a particular station, compo- 
nent, line, or application program by coding the OPDATA= operand of the 
TERMINAL or TPROCESS macro (see the example below). An OPTION macro 
merely gives an option field a name and describes the type and length of the field 
in assembler language format; an area of storage is neither initialized nor actually 
allocated for the field unless the field is specified for a particular station, compo- 
nent, line, or application program by means of the OPDATA= operand of the 
TERMINAL or TPROCESS macro. Up to 254 option fields, each of which may 
be as large as 255 bytes, may be defined in an MCP by OPTION macros. All or 
any part of the set of option fields may be allocated to each station, component, 
line, or application program represented by a terminal-table entry. For the set of 
option fields for a particular entry in the terminal table, the last option field must 
be within 254 bytes of the first. 

A new area of storage having the name and attributes specified by the OPTION 
macro defining an option field is assigned to each station, component, line, or 
application program whose TERMINAL or TPROCESS macro initiaUzes that 
field. Each TERMINAL or TPROCESS macro may initiaUze a field differently; 
hence different stations, components, lines, or application programs may be 
assigned option fields having identical names and attributes, but different con- 
tents. This feature allows the user to tailor the functions of a macro gaining access 
to an option field to meet the needs of a particular station, component, line, or 
application program. For example, the COUNTER macro maintains a count of 
messages or message segments received from or sent to a station. This counter is 
located in an option field for that station. If the OPTION macro for this field is 
named COUNT, and if the COUNTER macro names COUNT as the field in 
which the counter should be maintained, then a separate counter will be main- 
tained for each station that uses the OPDATA= operand of the TERMINAL 
macro to initialize COUNT. 

A macro coded in an inheader, inbuffer, or inmessage subgroup handUng messages 
entered by stations on a line gains access to the specified option field for the 



Defining Terminal and Line Control Areas 21 



opfldname 



typelength 



Station that entered the message being processed. (If the originating station is 
unknown because it called in on a switched line and failed to identify itself, access 
to specified option field for the line entry associated with this line is gained.) A 
macro coded in an outheader, outbuffer, or outmessage subgroup handling 
messages destined for stations on a line gains access to the specified option field 
for the station that is to accept the message being processed. A macro coded in an 
outheader, outbuffer, or outmessage subgroup handling messages destined for an 
application program, gains access to the specified option field associated with the 
process queue to which the GET or READ macro that is moving this message to 
the appHcation program is directed. A macro coded in an inheader, inbuffer, or 
inmessage subgroup handling messages being received from an application pro- 
gram gains access to the specified option field for the process entry associated 
with the DCB named in the PUT or WRITE macro. 

OPTION has the following format: 



Name 


Operation 


Operand 


opfldname 


OPTION 


typelength 



Function: Specifies the name of the option field. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the type and length of the option field. 

Default: None. This operand must be specified. 

Format: Standard assembler language format (for example, H, CL8, AL3). All 

assembler language codes may be used. However, B, C, P, X, and Z must be 

coded with a length attribute (for example, CL5, BL4). Duplication factors are 

not allowed; that is, ABC OPTION 3DL5 is an invalid macro. 

Notes: When the option field is used in conjunction with the FORWARD, 

ERRORMSG, or REDIRECT macro, a character string of length n must be 

specified, where n is the length in bytes of the data in the OPDATA= operand of 

the TERMINAL or TPROCESS macros that initialize the fields. 

If used with counter, typelength should be specified as H, since this macro requires 
a half word field on a half word boundary. 

If used with INBUF, INHDR, INMSG, OUTBUF, OUTHDR, OUTMSG, PATH, 
or MSGLIMIT macros, typelength should specify a one-byte field (for example, 
FLl, ALl). No boundary alignment is required. 

If used with STARTMH, typelength will specify a one- or four-byte field, depend- 
ing upon which STARTMH operand names the option field. 

Points to remember: 

• OPTION macros, if used, must be issued as a group and must immediately 
follow the TTABLE macro. 

• The order in which OPTION macros are arranged determines the order in 
which initiaUzation data must be specified in the OPDATA= operand of the 



22 OS/MFT and OS/MVT TCAM Programmer's Guide 



TERMINAL or TPROCESS macro. If a field specified by an OPTION macro 
is not to be defined for a particular station, component, line, or application 
program, then a comma should be coded in place of the data for this field in the 
OPDATA= operand (but trailing commas should not be coded). 
OPTION macros should be arranged so as to prevent waste of storage space in 
the option table. For example, if three OPTION macros are coded 

AA OPTION FL1 
AB OPTION CL4 
AC OPTION H 

the halfword specification for the AC field causes the assembler to perform 
boundary alignment. Since the AC field may not already be on a halfword 
boundary, one byte of storage area in the option table may be wasted for each 
terminal for which these option fields are defined. To conserve storage space, 
the above macros should be coded as follows: 



AC OPTION H 
AA OPTION FL1 
AB OPTION CL4 

If four OPTION macros are coded 

BA OPTION F 
BB OPTION CL1 
BC OPTION H 
BD OPTION CL1 

two bytes of storage area in the option table will be wasted for each station 
after the first for which these option fields are defined. To conserve storage 
space, the macros should be coded: 



BA OPTION F 
BC OPTION H 
BB OPTION CL1 
BD OPTION CL1 

• In coding an OPTION macro, the user must specify the type and length of the 
option field to be generated. This information is contained in the discussion of 
the individual macro that gains access to the option field. 

Example: 

In the following example, the TTABLE macro defines the beginning and end of 
the terminal table section of the Message Control Program. The OPTION mac- 
ros, which are a part of this section of code, define fields in the option table that 
are used by the COUNTER, MSGLIMIT, REDIRECT, ERRORMSG, and PATH 
macros. 





TTABLE 


LAST=:PROC 


COUNT 


OPTION 


H 


MSGLMT 


OPTION 


FL1 


REDRECT 


OPTION 


CL3 


ERRMSG 


OPTION 


CL4 


PATHSW 


OPTION 


FL1 



TTABLE defines PROC as the name of the last entry in the terminal table. The 
I OPTION macros define an 11 -byte optional area for entries in the terminal table. 

The optional area consists of five fields: 



Defining Terminal and Line Control Areas 23 



• COUNT defines a halfword for decimal data to be used by the COUNTER 
macro. 

• MSGLMT defines one byte for decimal data to be used by the MSGLIMIT 
macro. 

• REDRECT defines a character string consisting of three bytes naming the 
terminal; this data is used by the REDIRECT macro. 

• ERRMSG defines a character string consisting of a four-byte terminal name; 
this data is used by the ERRORMSG macro. 

• PATHSW defines one byte for eight binary path switches to be tested by 
various delimiter macros. 

If the OPDATA= operand of a TERMINAL macro were coded 

OPDATA=( 0,0, NYC, PITT, 3 ) 

an 1 1-byte storage area would be set aside in the option table for use by MH 
macros in handUng messages to and from that terminal. The COUNT and 
MSGLMT fields would initially contain 0, the REDRECT field would contain 
NYC, the ERRMSG field would contain PITT, and the PATHSW field would 
contain 3. 

If the OPDATA= operand of another TERMINAL macro were coded 

OPDATA=( ,, NYC, PITT) 

a 7 -byte storage area would be set aside in the option table for use by MH macros 
in handUng messages to and from that terminal. Only the REDRECT and 
ERRMSG fields would be created. 

Note that for an option field to be created for any particular terminal, two condi- 
tions must be satisfied: 

1 . An OPTION macro defining the field must be issued. 

2. The field must be initiaUzed in the OPDATA= operand of the TERMINAL 
macro for that terminal. If a comma is coded in place of a field in the 
OPDATA=s operand, no space is set aside for that field. If the OPDATA= 
operand of a TERMINAL macro is omitted, no option fields are set aside for 
that terminal. 



24 OS/MFT and OS/MVT TCAM Programmer's Guide 



TERMINAL 



The TERMINAL macro 

• creates a single, group, or line entry in the terminal table; 

• specifies the type of queuing to be used (that is, queuing by Une or queuing by 
terminal)*; 

• specifies the addressing characters to be used in addressing a station; 

• specifies when the computer is to initiate contact with switched stations; 

• specifies how often the computer is to initiate contact with switched stations; 

• designates secondary operator control stations; 

• specifies initial data for the option table; 

• specifies an alternate destination for messages sent to the station for which this 
TERMINAL macro is issued; 

• overrides the buffer size specified by the BUFSIZE= operand of the Une group 
DCB, for output only; 

• specifies blocking factors to be used for inserting control characters in outgoing 
messages destined for this station, when a MSGFORM macro is executed in an 
outheader subgroup handling such messages; 

• is required for each single or group station or line entry in the TCAM system. 

The TERMINAL macro causes an EBCDIC name of a station or line, and infor- 
mation associated with the station or line, to be included as an entry in the termi- 
nal table. If a single station or component is involved, TERMINAL produces a 
single entry in the terminal table. If a group of stations having the group address- 
ing feature is involved, TERMINAL produces a group entry. If a Une is involved, 
TERMINAL produces a line entry. 

One TERMINAL macro should be coded for: 

L Each station (whether switched or nonswitched) that can accept messages, and 
for some terminals that can only enter messages (see Coding the TERMINAL 
Macro for a Line below). 

2. Each group of nonswitched terminals equipped with the group addressing 
feature. Terminals can only accept messages under the group addressing 
feature; they cannot enter messages. Each terminal in the group that can also 
enter messages, or that can be addressed separately, must also be represented 
by a single entry. 

3. Each switched line to stations that do not uniquely identify themselves after 
calling the computer. 

For guidelines on coding the TERMINAL macro for a Une and for a component, 
see the next two sections of this chapter. 

TERMINAL macros for stations on a line must be issued together, and the groups 
of TERMINAL macros for each Une in a line group must be in ascending relative 
Une sequence. 

When TERMINAL macros are issued for the individual components of a station, 
the macros for the components must immediately follow that for the station. 



Defining Terminal and Line Control Areas 25 



See Appendix G. Device-Dependent Considerations , for particular specifications 
for the 

1030 Station; 

2260 Display Station (remote); 

2740 with Station Control or Station Control and Checking feature; 

2740 with the Transmit Control or Transmit Control and Checking feature; 

2740 Basic Terminal; 

2740 Model 2 Communications Terminal; 

2741 Communication Terminal; 
2770 Data Communications System; 
2790 Data Communications System; 
IBM 3270 Information Display System 
IBM 3670 Brokerage Communication System 
IBM 3780 Data Communication Terminal 
BSC stations; 
AT&T83B3 stations. 

TERMINAL has the following format: 



Name 


Operation 


Operands 


symbol 


TERMINAL 


QBY= (T ) 

,DCB=dcbname 
,RLN= integer 
,TERM=type 
,QUEUES=form 
[,DIALNO=(chars )] 
iNONEj 
[,ADDR=chars] 
[,LEVEL=(integer,...)] 
[,CLOCK=time] 
[,CINTVL=integer] 
[,BUFSIZE=integer] 
[,ALTDEST=entry] 
[,BFDELAY=ipteger] 
[,NTBLKSZ=(blocksize,subblocksize)] 
[,TBLKSZ=integer] 
[,OPDATA=(data,...)] 
[,RETRY=mteger] 
[,LMD=lYESl] 

(no/ 

[,MB= jYESa 
(NO/ 
[,SECTERM=(YES)] 

\NO f 
[,FEATURE=fATTN \ 

Inoattn/ 

[,COMP= (YES)] 
|NO / 
[,UTERM=/YESn 

|no f 



26 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



Function: Specifies 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 

Notes: This name can appear in an origin or destination field of a message 

header. SYSCON may not be used. 

If more than one TERMINAL macro is specified for the same buffered station (by 
coding two TERMINAL macros, with different names, for the same station), 
message segments may become intermixed during sending or receiving operations. 
Furthermore, a text segment may be treated as a header segment. For these 
reasons, coding more than one TERMINAL macro for the same buffered station 
is not a recommended procedure, unless the TERMINAL macros are coded for 
components rather than for the station itself. 



QBY= 



{1} 



Function: Specifies the type of message queuing 
Default: None. This operand must be specified. 
Format: T or L. 

Notes: T specifies that outgoing messages are to be queued by station; that is, all 
messages for a given station on a Hne are sent in priority order before any mes- 
sages for other stations on that line are sent (except for 2770 stations for which 
BFDELAY= is coded; messages are sent to these stations a buffer at a time). T 
should be specified for switched stations, and must be specified for stations using 
TCAM's buffered-terminal support or for a TCAM terminal that includes logical 
messages. For a more complete discussion of queuing by station, see Maintaining 
Orderly Message Flow in this chapter. L specifies that outgoing messages are to 
be queued by line; messages for all stations on the Hne are sent on a first-ended 
first-out basis within priority groups. If L is specified for stations on a switched 
line, when contact is made with a station on that Hne, all messages on the queue 
are sent to that station, regardless of what station they are intended for. For a 
more complete discussion of queuing by line, see Maintaining Orderly Message 
Flow in this chapter. This operand is ignored if the TERMINAL macro is coded 
for a component or for a line (that is, the UTERM= operand of the TERMINAL 
macro must either be omitted or must specify NO). 



DCB:=dcbnanie 



RLN= integer 



Function: Specifies the name of the data control block for the line group in which 

the station is included. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the relative line number, within the Hne group, of the access 

line over which the computer and the station communicate. 

Default: None. This operand must be specified. 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: For a discussion of how relative line numbers are assigned, see DD 

Statements for a Line Group . For a switched station on a line for which no 

TERMINAL macro coded for a line is issued and for which no message priority is 

used, any access line in the group may be specified. When the computer calls a 



Defining Terminal and Line Control Areas 27 



TERIVl=type 



QUEUES=foriii 



Station assigned to a switched line, it attempts to make the call using the line 
whose relative line number is specified. If that line is unavailable, the Hne whose 
relative line number is greater than that specified by integer is examined; this 
process is repeated until a free Hne is found or until all lines in the group that have 
relative Une numbers higher than the integer specified for this station have been 
examined. If all higher-numbered Unes in the hne group are unavailable, the 
station is not dialed at this time. Dialing is postponed until a suitable line is 
available. 

If message priority is used for switched Hnes for which no TERMINAL macro 
coded for a line is issued, this operand should be coded RLN= 1. 



Function: Specifies the terminal type. 
Default: None. This operand must be specified. 

Format: This operand may be replaced by any of the following values. 1030, 
1050, 1060, 226L (2260 Local), 226R (2260 Remote), 226C (2260 Control), 
2265, 274 A (nonswitched Basic 2740 Model 1), 274B (switched 2740 Model 1), 
274C (nonswitched 2740 Model 1 with Station Control), 274D (nonswitched 
2740 Model 1 with Station Control and Checking), 274E (switched 2740 Model 1 
with Transmit Control and Checking), 274F (nonswitched 2740 Model 1 with 
Checking), 274G (switched 2740 Model 1 with Checking), 274H (switched 2740 
Model 1 with Transmit Control), 2741 (2740 Model 2 with Checking), 274J 
(2740 Model 2 without Checking), 2741, 2760, 277A (polled 2770), 277B 
(non-polled 2770), 278A (polled 2780), 278B (non-polled 2780), 373A (polled 
3735), 373B (non-polled 3735), 7770, 113A (polled 1130), 113B (non-polled 
1 130), 202A (polled Model 20), 202B (non-polled Model 20), 83B3, 1 15A 
(Western Union Plan 115A outstations on a nonswitched network), 3335 (AT& T 
33/35 Dial), WTTY (World Trade telegraph terminals), S36B (non-polled 
System/360). 327C (3270 Remote Control), 327L (3270 Local), 327R (Remote 
Clustered), 327S (3270 Standalone Remote), 367A (Polled 3670), 367C 
(Broadcast 3670), BSCl, BSC2, BSC3. 

BSCl, BSC2, and BSC3 are convenient ways of specifying a category of termi- 
nals. BSCl represents point-to-point, nonswitched terminals (113B, 180B, 202B, 
373B, S03B, S36B). BSC2 represents point-to-point switched terminals (same 
devices as BSCl). BSC3 represents multipoint terminals (113A, 180A, 202A, 
2972 (2970 Terminal), 363A (3670 Terminal), 367A, S03A, S36A (S/360). 
Notes: The TERM= operand can be written either of two ways. 



TERM=202A or TERM=BSC3 



Function : Specifies 

where the message queues are to be 

maintained. 

Default: None. This operand must be specified. 

Format: DR, DN, MO, MN, or MR. 

Notes: For a discussion of this topic, see Message Queues Data Sets . 

If queuing is by terminal, this operand must be specified for all TERMINAL 
macros for a station on the line. If queuing is by line, this operand must be 
specified for the first TERMINAL macro coded for a station on the line, but may 
be omitted for subsequent TERMINAL macros for stations on the line. 



28 OS/MFT and OS/M VT TCAM Programmer's Guide 



DIALNO= (chars ) 
(NONE ) 



ADDR=chars 



DR specifies reusable disk queues. 

DN specifies nonreusable disk queues. 

MO specifies main-storage-only queues. 

MR specifies main-storage queues with backup on reusable disk. 

MN specifies main-storage queues with backup on nonreusable disk. 

If MO is specified, the distribution Ust, multiple routing, and REDIRECT facilities 
should be used with care, since one extra buffer is required to accommodate every 
destination other than the original destination. 

If the form of data set specified by this operand does not correspond to a related 
message queues data set specified in the DCB, TCAM terminates abnormally. 

If MO, MR, or MN is specified, the MSUNITS= operand of the INTRO macro 
must specify a nonzero integer; otherwise, the TERMINAL macro does not 
assemble properly and an MNOTE is generated. 



Function: Specifies the telephone number of the station. 
Default: None. Specification optional. 

Format: chars or NONE, chars is a decimal field with no framing characters. 
Notes: This operand tells TCAM whether a station is on a switched or a non- 
switched Une, and it must be specified for switched stations, chars is the tele- 
phone number of the station. 

DIALNO=chars must be specified if the CINTVL= operand of this macro is 
specified. DIALNO=NONE specifies that this station is on a switched line, but 
the computer may not initiate calls to it. DIALNO=NONE must be specified if 
the transmission control unit for the line over which contact is to be established 
with the station does not have the Auto Call feature and should be specified if 
Inward WATS lines are to be used to best advantage. The user also must specify 
all optional features (for instance. Auto Call and Auto Answer) at system genera- 
tion time for lines or their related terminals. 

If this operand is omitted, the station for which this TERMINAL macro is coded 
is assumed to be on a nons witched line. 



Function: Specifies the addressing characters for the station, or specifies the 

end-to-end control sequence for switched or nonswitched point-to-point 2770 or 

2780 stations. 

Default: None. Specification optional. 

Format: Unframed hexadecimal equivalent of the appropriate transmission-code 

representation. 

Notes: Addressing characters are used by the central computer to inform a 

station that the computer wishes to send it a message. For information on the 

addressing characters for a specific station, see the hardware manual for that 

station. 

If a station is assigned an ID sequence rather than addressing characters, this 
operand is not coded; the ID sequence is entered in the invitation list (see the 
discussion of the INVLIST macro). 



Defining Terminal and Line Control Areas 29 



LEVEL= (integer,...) 



CLOCK =time 



CINTVL=:integer 



This operand must also specify the end-to-end control sequence for a point-to- 
point 2770 or 2780 station. For information on the end-to-end control sequence, 
see the appropriate hardware manual. The end-to-end control sequence is speci- 
fied by writing the equivalent of the appropriate transmission-code representation, 
and must be immediately preceded by the STX line-control character and immedi- 
ately followed by the ETB line-control character. 



Function: Specifies the permissible priority levels that may be used in the header 
of a message destined for this station. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: The levels must be specified in increasing order. For instance, if the 
messages being sent to a certain station can have priorities of 1, 9, or 1 1, the 
LEVEL = operand for this station would be coded LEVEL =(1,9,1 1). If queuing 
is by Une rather than by terminal, the priority levels specified in the first 
TERMINAL macro coded for a station on the Une will apply to all stations on that 
line; in this case, the LEVEL = operand of subsequent TERMINAL macros for 
the same line is ignored. 

For more information on message priority, see the discussion of the PRIORITY 
macro and Message Priority and Queuing in this chapter. 



Function: Specifies the time of day that the computer should initiate contact with 
a switched station. 

Default: None. Specification optional. 

Format: Two decimal integers for the hours, immediately followed by two 
decimal integers for the minutes. Framing characters may not be specified. 
Maximum: 2359 (that is, 23 for the first field, 59 for the second). 
Notes: If this operand is specified, CINTVL= must be omitted and DIALNO= 
must specify the dial digits to be used. If CLOCK= and CINTVL= are both 
omitted, the computer does not periodically initiate contact with this switched 
station. When CLOCK= is specified, the only time that the switched station will 
be sent messages is when the computer initiates contact with it (at the time of day 
specified by this operand). If the station calls in at any time other than that 
specified by this operand, it may enter messages but will not be sent any messages 
by the computer (except that a station locked to an appUcation program will get its 
lock responses). This operand is used to take advantage of low toll times. If there 
are no messages queued for the station at the appropriate time, TCAM will dial 
the station and invite it to enter messages. 



Function: Specifies the number of seconds following which the computer should 

initiate contact with a switched station, if neither the station nor the computer 

called the other during this period. 

Default: None. Specification optional. 

Format: Unframed decimal integer. 

Maximum: 65535 

Notes: The interval is restarted at the termination of each call from the station, 

or when the computer calls the station to send its messages. If CINTVL= is 

specified, DIALNO= must also be specified, and CLOCK= must be omitted. 

The first interval starts when the line group data set for this Une is opened. This 

operand can be used to take advantage of Outward WATS. 



30 OS/MFT and OS/MVT TCAM Programmer's Guide 



BUFSIZE=integer 



ALTDEST=eiitry 



BFDELAY=integer 



Function: Specifies the buffer size, in bytes, for outgoing messages destined for 

this station, and overrides the BUFSIZE= operand of the Hne group DCB macro. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the buffer size specified in the Une group DCB is 

used. 



Function: Specifies the alternate destination to which a message on a reusable 

disk queue is sent at the time the zone containing the message is serviced for 

reuse. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols, and specify 

the name of any single, group, or process entry in the terminal table capable of 

accepting messages. Framing characters must not be specified. 

Notes: See Reusable Disk Queues for a description of servicing for reuse. When 

the destination queue defined by a TERMINAL macro is reorganized, unsent 

messages on the queue are placed on the destination queue specified by the 

ALTDEST= operand. ALTDEST= may specify the original destination as well 

as any other vaUd destination. If the ALTDEST= operand is omitted, messages in 

a reusable disk queue may be written over and lost to the system with no error 

indication being made. This operand is ignored unless either QUEUES =DR or 

QUEUES = MR is specified in this TERMINAL macro. 



Function: Specifies the number of seconds of delay to be used before another 
message block is sent to a buffered station (to avoid sending another message 
block while the hardware buffer is still emptying the previous block of data). 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum : 65535 

Notes: integer should specify the average time needed to empty the hardware 
buffer. This may be computed from the number of characters in the hardware 
buffer and the rate at which characters are transferred from the buffer to the 
terminal component. 

This operand must be coded for IBM 2740 Model 2 and multipoint IBM 2770 
stations and must not be coded for any other station. For information on 
TCAM's buffering feature, see Transmission Priority for Nonswitched Polled 
Stations Using TCAM's Buffering Feature in this chapter. 

The BFDELAY= operand must either be included in all TERMINAL macros for 
stations on the same line, or omitted from all TERMINAL macros for stations on 
the Une. When this operand is coded, queuing by station and send priority should 
also be specified. If stations using a buffer delay are intermixed with nonbuffered 
stations on the same line (this can be done because BSC stations are compatible), 
BFDELAY=0 should be specified in the TERMINAL macros for the nonbuffered 
stations. The BFDELAY= operand should not be specified for start-stop or BSC 
stations on switched or point-to-point lines. 



Defining Terminal and Line Control Areas 3 1 



NTBLKSZ=(blocksize, subblocksize) 



Function: Specifies blocking factors for outgoing messages in non transparent 

mode directed to this station. 

Default: None. Specification optional. 

Format: Unframed decimal integer. 

Maximum: For blocksize , 65535. For subblocksize ,255. 

Notes: blocksize is the number of bytes in each block of data in nontransparent 

mode for messages directed to this station, when the MSGFORM macro is coded 

in the outheader subgroup handling these messages. 



blocksize is used when LC=OUT is specified in the STARTMH macro to indicate 
where BOB or ETB line-control characters are to be inserted in outgoing mes- 
sages. If a block size of 100 were specified, an EOB or ETB would be inserted 
after every 100 characters in the message, provided that the message were handled 
by an outheader subgroup that contains a MSGFORM macro. The value specified 
here may be overridden by coding the BLOCK = operand of the MSGFORM 
macro; if the blocksize suboperand is omitted from the TERMINAL macro, 
MSGFORM may still be used to specify the blocking factor. The character 
inserted is not considered part of the block. 

subblocksize is the number of bytes in each subblock of data in nontransparent 
mode for messages directed to this BSC station. It is used when LC=OUT is 
specified in the STARTMH macro to indicate where ITB line-control characters 
are to be inserted in outgoing messages. If a subblock size of 100 were coded, an 
ITB would be inserted after every 100 characters in the message, provided that 
the message were handled by an outheader subgroup that includes a MSGFORM 
macro. The value specified here may be overridden by coding the SUBBLOCK= 
operand of the MSGFORM macro; if the subblocksize suboperand is omitted 
from the TERMINAL macro, MSGFORM may still be used to specify the number 
of bytes per subblock. The ITB inserted is not considered part of the block. 



{ 



32 OS/MFT and OS/MVT TC AM Programmer's Guide 



TBLKSZ=integer 



OPDATA=(data,...) 



Function: Specifies the number of bytes in each block of data for outgoing 
messages in transparent mode. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 65535 

Notes: The appropriate line-control sequence is transmitted after each number of 
bytes of data specified by integer , provided that the MSGFORM macro is coded 
in the outheader subgroup handling this message, and provided that 
SENDTRP=YES is coded in MSGFORM. The value specified here may be 
overridden by coding the BLOCK= operand of the MSGFORM macro. If the 
TBLKSZ= operand is omitted from the TERMINAL macro, MSGFORM may 
still be used to specify the blocking factor for outgoing messages in transparent 
mode. 



Function: Specifies the actual data to be inserted in the set of option fields 
assigned to this station (see the discussion of the OPTION macro), and also 
specifies which option fields are not to be created for this station. 
Default: None. Specification optional. 

Format: The maximum length and type of data specified for each option field 
must correspond to the length and type specified by the OPTION macro that 
defines the field, and the order in which the data for each field is specified must 
correspond to the order in which the OPTION macros are specified. Framing 
characters are not used. 



Defining Terminal and Line Control Areas 33 



Notes: When specifying option fields for a particular station, the user may omit 
the last several option fields defined by OPTION macros by merely closing the 
parenthesis after the data for the last field he wishes to define. A comma is used 
to: 

1. Delimit the data for each field; 

2. Indicate that no data is specified for the first or an intermediate field defined by 
an OPTION macro; 

3. Indicate that the OPDATA operand is to be continued (if specified immediately 
preceding the right parenthesis — see note below). 

The user must specify either data and a comma, or a comma alone for the first and 
each intermediate field (except the last) that is specified by an OPTION macro 
(with one exception — see the note below). A comma alone is coded if a field 
other than the last is not to be defined for this station. If the last field is not to be 
defined, no data is coded for the field and the comma is also omitted. Framing 
characters (X or C and quotes) are not coded. 

Example: 

Assume that four OPTION macros have been coded. If the user wants to specify 
all four fields for a particular station, line, or application program, he would code 
the OPDATA= operand of the TERMINAL or TPROCESS macro as follows: 

,OPDATA=( fieldl , f ield2 , f ield3 , f ield4 ) 

where fieldl , fieldl , fields , and field4 represent the actual initial data to be 
inserted into each of the four option fields. If only fieldl and field4 are to be 
implemented for this station, line, or appHcation program, the user would code 

,OPDATA=( fieldl , , , f ield4 ) 
If only fieldl , fieldl , and fields are to be implemented, the user would code 

,OPDATA-( fieldl , f ield2 , f ield3 ) 
If only fieldl is to be implemented, the user would code 

,OPDATA=( fieldl ) 

Because one operand of a macro is limited to 255 characters, TCAM provides a 
facility to specify additional OPDATA= parameters if necessary. A comma 
placed as the last character of the OPDATA= operand — that is, 

,OPDATA=( data, data, . . .data, ) 

indicates a continuation of the OPDATA = operand. The next source statement 
would then be coded 

symbol TERMINAL OPDATA=( data, . . . ) 

where symbol is the name specified on the TERMINAL macro that specified the 
continuation. 

There is no limit (other than the number of option fields defined) on the number 
of continuation statements that may be used. 



34 OS/MFT and OS/MVT TCAM Programmer's Guide 



RETRY=integer 



LMD= f yes) 



ivib=(yes ) 

JNOI 



Function: Specifies the maximum number of times the CPU is to retry dialing a 

switched station. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than zero. 

Maximum: 255 

Notes: This operand is required if the RETRY macro is specified in the inmessage 

subgroup. This TERMINAL macro also must specify the DIALNO= operand and 

either the CLOCK= or the CINTVL= operand. 

A HOLD macro with bit 26 specified in the mask should be coded in the outmes- 
sage subgroup so that no messages will be lost if the retry count is reached without 
the CPU having initiated contact with the switched station. However, if the 
CLOCK = operand is specified, the user must assure that messages are released 
before the specified time expires again in order for them to be sent to the station 
when the time does expire. 



Function: Specifies whether individual logical messages entered by this station 
may be included in multiple physical transmissions. 
Default: LMD=NO 
Formal: YES or NO 

Notes: YES indicates that any individual logical message entered by this station 
may be in more than one transmission sequence (that is, if part of a logical 
message is entered in a transmission sequence, the remainder of the message may 
be included in the station's next transmission sequence — two or more transmission 
sequences may be used to enter this message). This allows an incoming logical 
message to be larger than the physical limitations imposed by the source station. 
No intervening data may be included between the beginning and the end of the 
logical message. YES must be coded if this station is a 2715. 

If this operand is omitted, or if NO is specified, logical messages entered by this 
station must be entered in their entirety in a single transmission sequence. 

Logical messages are discussed in Handling Logical Messages in the chapter 
Defining the Message Handler. 



Function: Specifies whether mid-batch recovery is to be performed when a 

permanent text error is encountered in a multiblock message to or from a station. 

Default: MB=NO 

Format: YES or NO. 

Notes: YES indicates that mid-batch recovery is to be performed. If NO is 

specified, or if this operand is omitted, an entire message is canceled when a text 

error is encountered. 



Defining Terminal and Line Control Areas 35 



For incoming operations, the STARTMH macro must specify STOP = YES, and 
the inmessage subgroup must contain a CANCELMG macro that specifies 
LEVEL=BLK. 

For outgoing operations, also include the LEVEL =BLK operand on the HOLD 
macro and the QBY=T operand on the TERMINAL macro. 

MB = YES is the default for both switched and buffered stations; the MB= 
operand need not be specified for a switched or buffered station. Queuing by 
terminal is required for mid-batch recovery on both input and output operations. 



feature=Jattn ) 
i noattn i 



Function: Allows for the disposition of CPU transmission interrupted by IBM 
1050 and IBM 2741 terminals. 

Default: FEATURE = NOATTN Specification of this operand is optional. 
Format: ATTN or NOATTN. 

Notes: ATTN or NOATTN may be specified for both the IBM 1050 and the IBM 
2741 terminals equipped with an attention key. If ATTN or NOATTN is speci- 
fied for a terminal other than a 1050 or 2741, the entry is ignored. 

ATTN specifies that the station receiving data from the CPU can interrupt the 
CPU during the transmission. The user can provide for the disposition of the 
interrupted message by using functional macros in his MH. If this entry is omit- 
ted, and if the attention key is active for this station, interrupted CPU transmis- 
sions are handled as errors with no recovery for the interrupted message. 



secterm=Jyes ) 



Function: Specifies whether this station may be considered a secondary operator 

control station. 

Default: SECTERM=NO 

Format: YES or NO. 

Notes: If YES is specified, operator commands will be recognized, acted upon, 

and the appropriate response returned to the station. The station for which 

SECTERM=YES is specified must be on a nons witched line and must be able to 

both enter and accept messages. If a station other than the system console is to be 

the primary operator control station, SECTERM= YES must be specified for that 

station's TERMINAL macro. 



COMP= JYESl 



Function: Specifies whether or not this TERMINAL macro is being used to define 

a component of a station defined by another TERMINAL macro. 

Default: COMP=NO 

Format: YES or NO. 

Notes: If this operand is coded COMP= YES, then the TERMINAL macro is for 

a component. If the operand is omitted or COMP=NO is coded, then the macro 

is not for a component. 

For guideUnes on coding this operand, see Coding the TERMINAL Macro for 
a Component in this chapter. 



{ 



36 OS/MFT and OS/MVT TCAM Programmer's Guide 



UTERM= /YES\ 

mi 



Function: Specifies whether or not this TERMINAL macro is being used to define 
a Une entry in the terminal table. 
Default: UTERM=NO 
Format: YES or NO. 

Notes: If this operand is coded UTERM=YES, then the TERMINAL macro is 
for a line. If the operand is omitted, or if UTERM=NO is coded, then the 
TERMINAL macro is either for a station or a component — if coded for a station, 
this TERMINAL macro also must specify the QBY= operand. 

For information on coding this operand, see Coding the TERMINAL Macro 
for a Line in this chapter. 

Coding the TERMINAL Macro for a Component 

If the COMP= operand of a TERMINAL macro is coded COMP=YES, then the 
TERMINAL macro is one defining a component of a station defined by another 
TERMINAL macro. A TERMINAL macro need be issued for a component only 
if messages may be directed to more than one component of a station by means of 
appropriate addressing characters. If addressing characters are not used, a 
TERMINAL macro for a component is unnecessary. If a message can be sent to 
only one component of a terminal assigned addressing characters, that component 
may be specified by coding the appropriate addressing characters in the ADDR= 
operand of the TERMINAL macro for the terminal. For an IBM 1050 terminal 
assigned addressing characters, for example, the second addressing character 
identifies the component that is to receive the message. If only one component is 
to receive messages, that component's selection character may be entered as the 
second addressing character in the ADDR= operand of the TERMINAL macro 
for the terminal, and no TERMINAL macro need be issued for the component. If 
more than one component of a station is to be specifically addressed by means of 
addressing characters, then one or more component TERMINAL macros must be 
issued; these should immediately follow the TERMINAL macro for the station to 
which the components belong. 

The following operands of the TERMINAL macro are meaningful if the macro is 
issued for a component: 

ADDR=chars 

specifies the addressing characters for this component. 

ALTDEST=entry 

specifies the alternate destination to which a message on a reusable disk queue is 
sent at the time the zone containing the message is serviced for reuse (see 
Reusable Disk 12"^"^'^ for ^i description of this servicing). Any terminal, compo- 
nent, or process entry for a device capable of accepting messages may be speci- 
fied. If the operand is omitted, messages in a reusable disk queue may be written 
over and lost to the system with no error indication being made. 



Defining Terminal and Line Control Areas 37 



SECTERM=\ YES 



J YES I 
] NO ) 



Specifies whether repUes to operator commands entered at this station are to be 
sent to this component. If so, this component must be represented in the invita- 
tion Ust for this Une. If the station is polled, the operator command must have 
been entered in response to polling characters associated in the invitation list with 
an entry having the same name as the name of this terminal entry. (However, the 
two entries having the same name need not refer to the same device — the polUng 
characters could poll a card reader, for example, while the addressing characters 
might address a printer). 

NTBLKSZ=(blocksize,subblocksize) 

specifies blocking factors for outgoing messages in nontransparent mode directed 
to this station, blocksize and subblocksize have the same meanings as those 
described above in the discussion of the TERMINAL macro for a station. 

TBLKSZ= integer 

specifies the number of bytes in each block of data for outgoing messages in 
transparent mode directed to this component. This operand is similar to the 
TBLKSZ= operand for the TERMINAL macro for a station, described above, 
and may be overridden by coding the BLOCK = operand of the MSGFORM 
macro, and specifying SENDTRP=YES in MSGFORM. 

BUFSIZE=integer 

overrides the buffer size specified by the BUFSIZE= operand of the line group 
DCB macro, but only for buffers containing outgoing messages destined for this 
component. If this operand is omitted, the buffer size specified in the Hne group 
DCB macro is used. 

OPDATA=(data,...) 

specifies the actual data to be inserted in the set of option fields assigned to this 
component (see the discussion of the OPTION macro), and also specifies which 
option fields are not to be created for this component. The description of the 
OPDATA= operand of the TERMINAL macro for a station also applies to the 
OPDATA= operand of the TERMINAL macro for a component. 

COMP=jYES( 
fNO S 

specifies whether this TERMINAL macro is for a component. COMP=YES 
indicates that this TERMINAL macro is for a component. 

Coding the TERMINAL Macro for a Line 

A TERMINAL macro whose UTERM= operand is coded UTERM= YES causes 
information to be included in the terminal table for a line to switched stations that 
do not uniquely identify themselves when calling the computer. 

As a general rule, a switched Une should have its own TERMINAL macro if any 
stations that do not always uniquely identify themselves call the computer on that 
line. If all stations calling in on a switched line always uniquely identify them- 



38 OS/MFT and OS/MVT TCAM Programmer's Guide 



selves, no TERMINAL macro is required for that line. The following considera- 
tions apply when deciding whether a particular switched line requires its own 
TERMINAL macro (see also Figure 1, which summarizes these considerations). 

1. A TCAM audio line (that is, a line connected to an IBM 7770 Audio Response 
Unit, Model 3) requires its own TERMINAL macro. 

2. A switched line to BSC stations that are all assigned unique ID sequences does 
not require its own TERMINAL macro. For such a Une, the user should enter 
each station's name and ID sequence, and the CPU ID sequence, in the appro- 
priate operands of the INVLIST macro for the line (see the discussion of the 
INVLIST macro). 

3. If none of the stations on a line ever dial the computer, the line needs no 
TERMINAL macro. Terminal names and invitation characters are coded in the 
INVLIST macro (see the discussion of the INVLIST macro). 

4. For a switched line to stations other than those described in (2) and (3) above, 
code a TERMINAL macro specifying UTERM=YES unless all messages 
entered by stations on the line have origin fields in their message header and 
are processed by a Message Handler subgroup containing an ORIGIN macro 
(see the discussion of the ORIGIN macro). For lines to stations that enter only 
messages having origin fields, see (5). When a TERMINAL macro is coded for 
a line, the name of the macro is entered together with the invitation characters 
for stations on the line in the appropriate operand of the INVLIST macro for 
the line (see the discussion of the INVLIST macro). 

5. For a switched line to stations other than those described in (2) and (3), if all 
messages entered on the line have vaUd origin fields in their message headers 
and are processed by a Message Handler subgroup containing an ORIGIN 
macro, then a TERMINAL macro may be specified for that line at the option 
of the user. If the TERMINAL macro is specified, the user must enter its name 
as part of the entry operand of the INVLIST macro for the line; otherwise the 
name of a TERMINAL macro for a station on the line is entered as part of the 
INVLIST entry. In either case, one INVLIST entry is coded for each series of 
invitation characters used by a station on the line (see the discussion of the 
INVLIST macro). 

In order to decide whether to code a TERMINAL macro for a Une under Case 5, 
the user must first understand the function of the ORIGIN macro and the origin 
field of the message header (discussed in the chapter Designing the Message 
Handler ) and must also understand the function of the OPTION macro (discussed 
in the present chapter). Then he should consider the following paragraphs. 

The TERMINAL macro has an optional OPDATA= operand. If a TERMINAL 
macro is coded for a switched line, when a station on that line dials the computer, 
access is gained to the option fields associated with the line entry, and these fields 
are possibly modified by Message Handler macros until an ORIGIN macro is 
encountered in the Message Handler. In addition, messages may be routed to the 
line entry; any station calling in will receive these messages until it is identified by 
an origin field checked by an ORIGIN macro. 

The ORIGIN macro establishes the identity of the calling station; once identity 
has been estabUshed, the option fields associated with the terminal entry for the 
station calling in are made available and possibly modified by Message Handler 
macros, and messages queued for the station are sent to it in the manner described 
in the section Transmission Priority in Defining Terminal and Line Control 
Areas . 



Defining Terminal and Line Control Areas 39 



c 



Start 



3 




Yes 



Yes 




Yes 



Yes 



Code Terminal 

Macro For 

Line 



Do Not Code 

Terminal 
Macro For Line 



Notes: I. Do you wish to send messages 

to unknown stations on the line? 
2. Do you wish to update any option 
fields on a line basis? 

Figure 1 . Determining whether a TERMINAL Macro Should Be Coded for a Switched Line 



Thus, if a user assigns no option fields to the stations on a switched Une, or if he 
does assign option fields but issues his ORIGIN macro in the Message Handler 
subsections handhng incoming messages before he issues any macros that modify 
option fields, he is safe in omitting the TERMINAL macro for that Une (but he 
may code the macro if he wishes to direct messages to any station caUing in on the 
Une). Otherwise, a TERMINAL macro specifying UTERM=YES should be 
coded for the line. AU TERMINAL macros for Unes in a line group must be 
arranged according to ascending relative Une number. The TERMINAL macro 
for a particular Une must immediately precede aU TERMINAL macros for stations 
on that Une. 

Example: 

The TERMINAL macros for three switched Unes in a line group, where each Une 
has three terminals associated with it, would be arranged in the foUowing order: 

• TERMINAL macro for relative line 1 (UTERM= YES) 

• TERMINAL macro for a terminal on line 1 

• TERMINAL macro for a second terminal on Une 1 

• TERMINAL macro for a third terminal on Une 1 

. TERMINAL macro for relative line 2 (UTERM= YES) 

• TERMINAL macro for a terminal on line 2 

• TERMINAL macro for a second terminal on line 2 

• TERMINAL macro for a third terminal on line 2 

. TERMINAL macro for relative line 3 (UTERM= YES) 

• TERMINAL macro for a terminal on Une 3 

• TERMINAL macro for a second terminal on line 3 

• TERMINAL macro for a third terminal on line 3 



40 OS/MFT and OS/MVT TCAM Programmer's Guide 



It may be that some lines in a line group have TERMINAL macros coded for them 
and others do not. In this case, arrange the TERMINAL macros for the stations 
on the Hnes in groups according to ascending relative line number, and place each 
TERMINAL macro for a line immediately in front of the group of TERMINAL 
macros for stations on that line. 

Example: 

The TERMINAL macros for three switched lines in a line group, where each Une 
has two terminals associated with it, and line 2 has no TERMINAL macro coded 
for it, would be arranged in the following order: 

. TERMINAL macro for relative Hne 1 (UTERM=YES) 

• TERMINAL macro for a terminal on line 1 

• TERMINAL macro for another terminal on line 1 

• TERMINAL macro for a terminal on line 2 

• TERMINAL macro for another terminal on Une 2 

• TERMINAL macro for relative Une 3 (UTERM=YES) 

• TERMINAL macro for a terminal on line 3 

• TERMINAL macro for another terminal on Une 3 

The following operands of the TERMINAL macro are relevant when the macro is 
specified for a Une: 

DCB=dcbname 
RLN=integer 
QUEUES=form 
TERM=type 
BUFSIZE=integer 
ADDR= chars 
OPDATA=data 
UTERM= (yes) 
INO j 

The DCB=, RLN=, and TERM= operands are the same as those given above for 
a TERMINAL macro for a station. 

For station-initiated calls that require a response, the ADDR= operand is coded 
only when the calUng station does not identify itself by an origin field in a message 
header. A caU from such a station would either: 

(a) cause the originating station to accept messages directed to the Une entry, 

(b) cause a response message to be sent back to the originating station by a 
MSGGEN macro in the Message Handler, or 

(c) place the originating station in lock mode (see the description of the LOCK 
macro) to await a response message from an application program. 

The ADDR= operand of the TERMINAL macro for a station must be coded if 
any messages are to be queued for that station. If the ADDR= operand of the 
TERMINAL macro for a line is coded, aU stations on the line must have identical 
addressing characters. 

The OPDATA= operand specifies the data to be inserted in the set of option 
fields assigned to this line. The operand is coded in the same way as the 
OPDATA= operand of a TERMINAL macro for a station. 

The QUEUES = operand is required, whether or not any messages are to be 



'f directed to the line entry as a destination. 



Defining Terminal and Line Control Areas 41 



When a station on this line dials the computer, access is gained to the option fields 
assigned to the line and the fields are modified by Message Handler macros until 
an ORIGIN macro in the Message Handler establishes the identity of the calling 
station. Once identity is established, the option fields assigned to the station 
calling in are updated by macros following the ORIGIN macro in the Message 
Handler. When the computer calls a station, only the option fields assigned to the 
station may be updated. 

The BUFSIZE= operand is optional and, if used here, overrides the BUFSIZE= 
operand of the line group DCB macro for messages directed to the line entry as a 
destination. 

The UTERM= operand, when coded UTERM=YES specifies that this 
TERMINAL macro is for a line. If the operand is omitted or coded 
UTERM=NO, this TERMINAL macro is not for a line. 



42 OS/MFT and OS/MVT TCAM Programmer's Guide 



TLIST 



The TLIST macro 

• defines a cascade list entry or distribution list entry in the terminal table; 

• is optional among macros defining the terminal table. 

The TLIST macro causes the name of a Ust of single, group, or process entries in 
the terminal table, together with information about the entries in the list, to be 
included as an entry in the terminal table. 

A distribution or cascade Ust consists of the names of single, group, or process 
entries in the terminal table. One TLIST macro must be specified for each Ust to 
be created. Stations cannot enter messages using either a distribution or a cascade 
list. 

When a message contains the name of a distribution Ust as a destination code, 
TCAM sends the message by separate transmissions to each station or appUcation 
program indicated by an entry in the Ust. Each entry in the Ust must have a 
corresponding single, group, or process entry in the terminal table. When a 
message contains the name of a cascade list as a destination code, TCAM places 
the message on the destination queue for that valid destination in the Ust that has 
the fewest messages waiting to be sent to it. If several destinations have the same 
number of messages, the message is queued for the first such destination Usted. 

The TLIST macro provides the initial contents for aU fields in the Ust entry. 



Name 


Operation 


Operands 


symbol 


TLIST 


TYPE= |DlLIST=(entry,entry,...) 



symbol 



TYPE= 



{?} 



Function: Specifies the name of the Ust. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies whether the Ust is a distribution or a cascade Ust. 

Default: None. This operand is required. 

Format: D or C. 

Notes: C specifies a cascade Ust. D specifies a distribution list. 



LIST= (entry ,entry,...) 



Function: Specifies the actual entries in the distribution Ust or cascade Ust being 

created. 

Default: None. This operand is required. 

Format: Each entry is the name of a single, group, process, or cascade list entry 

in the terminal table. If TYPE=D, at least two entries must be specified. If 

TYPE=C, only one entry is required. 

Notes: The name of a distribution Ust entry in the terminal table may not be 



Defining Terminal and Line Control Areas 43 



specified as an entry in a distribution list. If ttie list being created is a distribution 
list, it may contain the name of one or more cascade list entries. If it is a cascade 
list, it may not contain the name of a cascade list entry. 

Because of the limitation of 255 characters in a macro operand, a faciUty is 
provided to specify additional TLIST entries if necessary. A comma placed as the 
last character of the entries operand indicates a continuation of the Ust. The next 
source statement would then be coded: 

symbol TLIST LIST=( entry, . . . ) 

where symbol is the TLIST name as specified on the previous TLIST macro that 
indicated the continuation. There is a limit of 32767 entries in a distribution or 
cascade Ust. 



< 



44 OS/MFT and OS/MVT TCAM Programmer's Guide 



TPROCESS 



The TPROCESS macro 

• serves as part of the interface between the MCP and an application program; 

• creates a terminal table entry for a queue associated with an application pro- 
gram; 

• is optional among macros defining the terminal table. 

The TPROCESS macro causes the name of a queue for an application program 
and associated information to be included as an entry in the terminal table. The 
entry produced is a process entry. 

One TPROCESS macro must be included for each destination queue to which an 
application program can direct a GET or READ macro, and at least one must be 
included for each process entry to which a PUT or WRITE macro may be 
directed. 

An operand of the TPROCESS macro specifies the name of a process control 
block (PCB), which is used to establish communication between a Message 
Handler and application programs. (The PCB is created by coding a PCB macro.) 

Another operand of TPROCESS enables the user to specify one alternate destina- 
tion to which the message may be sent in certain circumstances. 

The user may specify that checkpointing of the application program is to be 
synchronized with that of the Message Control Program. Synchronization of OS 
with TCAM checkpoints is discussed in the chapter Writing TCAM-Compatible 
Application Programs. 

The user also specifies the initial contents of the option fields for the process entry 
in the terminal table. 

The TPROCESS macro helps connect an application program to the Message 
Control Program. The GET and PUT or READ and WRITE macros issued in an 
application program each specify the name of a data control block created by a 
DCB macro issued in the application program. The DCB macro specifies (by its 
DDNAME= operand) a DD card. The QNAME= parameter of the DD card 
names a process entry. The pcbname operand of the TPROCESS macro creating 
this entry specifies a process control block. The MH= operand of the PCB macro 
creating the process control block specifies the Message Handler that handles 
messages directed to and received from the application program. 



Defining Terminal and Line Control Areas 45 



TPROCESS has the following format: 



procname 



PCB=pcbname 



QUEUES=form 



Name 


Operation 


Operands 


procname 


TPROCESS 


PCB=pcbname[,QUEUES=form] 
[,ALTDEST=entry] 
[,CKPTSYN=/YES\] 
INOf 
[,DATE=4YES n 

Ino ] 
[,secterm= jyes/] 

JNOJ 
[,RECDEL=delimiter] 
[,LEVEL= (integer,...)] 
[,OPDATA=(data,...)] 

[,qback4yes(] 



Function: Specifies the name of the process entry in the terminal table. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: The name must be specified and must be the same as that entered in the 

QNAME= parameter of the DD statement associated with the DCB macro for an 

application program. 



Function: Specifies the name of the process control block that defines buffers, 

etc., to handle messages queued to this process entry. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The process control block is created by a PCB macro. All TPROCESS 

macros issued for the same application program must have the same PCB. 



Function: Specifies where the message queues containing messages for the applica- 
tion program are to be maintained (for GET/READ operations only). 
Default: None. Specification optional. 
Format: DR, DN, MO, MR, or MN. 

Notes: DR specifies reusable disk queues. DN specifies nonreusable disk queues. 
MO specifies main-storage-only queues. MR specifies main-storage queues with 
reusable disk backup. MN specifies main-storage queues with backup on nonreus- 
able disk. If the form of data set specified by this operand does not correspond to 
a related message queues data set defined by a DCB macro, the TCAM system 
terminates abnormally. By omitting the QUEUES = operand, the user specifies 
that this process entry is for PUTs or WRITEs from an application program (that 
is, do not code the QUEUES= operand for PUT/WRITE operations). 



If MO, MR, or MN is specified, the MSUNITS= operand of the INTRO macro 
must specify a nonzero integer; otherwise, the TPROCESS macro does not 
assemble properly and an MNOTE is generated. 



46 OS/MFT and OS/MVT TCAM Programmer's Guide 



ALTDEST=entry 



Function: If this process entry is for GETs or READs issued by an application 
program, this operand specifies the alternate destination to be sent when the zone 
containing the message is being serviced for reuse. If this process entry is for 
PUTs or WRITES from an application program, this operand specifies the destina- 
tion to which replies to operator commands issued by the application program are 
sent. 

Default: None. Specification optional. 

Format: The name of any single, group, or process entry in the terminal table. 
Notes: The entry specified may be the one created by the TPROCESS macro, 
preventing the message from being discarded from a reusable queue. If this 
operand is omitted for a GET or READ process entry, the message may be 
overlaid in a reusable queue and lost to the system. The operand is ignored unless 
QUEUES=DR or QUEUES=MR is specified for the TPROCESS macro. 

For a PUT or WRITE entry, the destination may be a station named by a 
TERMINAL macro, or it may be an appHcation program represented by a 
TPROCESS macro. 



ckptsyn=|yes) 
|no| 



Function: Specifies whether the destination queue to which the application 
program directs its GETs or READs is to be purged of serviced messages at 
restart. 

Default: CKPTSYN=NO 
Format: YES or NO. 

Notes: CKPTSYN= YES specifies that no purging of the queue is to be per- 
formed. If an OS checkpoint of the appHcation program is used in synchroniza- 
tion with the TCAM checkpoint, CKPTSYN=YES should be specified. If this 
operand is omitted, the queue is scanned and updated at restart. When synchroni- 
zation is not specified, operation following restart with scan resumes with the first 
unserviced message for the queue (a message is considered serviced when a GET 
or READ is issued for the next message from the queue and that next message is 
placed on the queue). The first unserviced message is determined in the scan of 
the message queue done at restart time. When not using synchronization with an 
OS checkpoint, it is necessary to check for one dupUcate message upon restart 
(that is, the message being processed when failure occurred). 



For more information on TCAM's checkpoint facility, see the chapter Using 
TCAM Service Facilities . Coordination of OS and TCAM checkpoints is dis- 
cussed in the chapter Writing TCAM -Compatible Application Programs . 



DATE=fYES\ 
JN0| 



Function: Specifies whether the date and time of each message received for the 
process entry are to be recorded. 
Default: NO 
Format: YES or NO 

Notes: When a message is received for the application program, TCAM records 
the date and time. When the appUcation program issues a GET or a READ 
macro, TCAM places the recorded date/time and the source of the message in the 
area specified by the DTSAREA= operand of the TPDATE macro. 



Defining Terminal and Line Control Areas 47 



SECTER1V1=\ YES 
NO 



Function: Specifies whether the application program may be considered a sec- 
ondary operator control station (so that operator commands may be sent to 
TCAM from the application program by using a PUT or WRITE macro). 
Default: SECTERM=NO 
Format: YES or NO. 

Notes: This operand is meaningful only if this process entry is associated with a 
PUT or WRITE macro, and is ignored if coded for a process entry associated with 
a GET or READ macro. If this PUT/WRITE process entry is to be the primary 
operator control station, SECTERM=YES must be specified for the entry. 



RECDEL=delimiter 



LEVEL=(iiiteger,...) 



Function: For a process entry associated with a GET or READ macro this 
operand specifies a one-byte, nonzero hexadecimal value used to delimit a record 
for the application program. For a process entry associated with a PUT or 
WRITE macro, this operand specifies a value to be inserted at the end of each 
variable-length record returned from an application program by means of a PUT 
or WRITE macro specifying the DCB associated (by coding the QNAME= 
operand of its DD card) with the process entry. 
Default: None. Specification optional. 
Format: A single, unframed hexadecimal character. 

Notes: This character may be inserted periodically into a TCAM buffer by coding 
a MSGEDIT macro with D AT A= DELIMIT for a process entry associated with a 
GET or READ. If the RECFM= operand on the input DCB macro specified by a 
GET or READ macro in the application program specifies V, VB, or U, and if the 
OPTCD= operand does not have the U suboperand coded in it, the application 
program GET or READ considers this character to be a record delimiter. The 
delimiter specified by RECDEL= may be included by the user in the incoming 
message, or may be inserted by means of a MSGEDIT macro. 

For a process entry associated with a PUT or WRITE macro, TCAM automatical- 
ly inserts the value at the end of each variable-length record. For other than 
variable-length records, this operand is meaningless. 



Function: Specifies the permissible priority levels that may be used in the header 
of a message enqueued on this process queue. 
Default: None. Specification optional. 

Format: Each integer is a decimal integer. Tht integer,... values must be speci- 
fied in ascending order. 
Maximum: 255 

Notes: If this operand is omitted, all messages sent to the application program by 
this process entry are assumed to have zero priority. If the messages being sent to 
the application program through this process entry can have, for example, priori- 
ties of 1, 9, or 11, the LEVEL= operand would be coded LEVEL=(1,9,11). 

For more information on message priority, see the discussion of the PRIORITY 
macro and Message Priority in this chapter. 



OPDATA=(data,...) 



Function: Specifies the actual data to be inserted in the set of option fields 
assigned to this process entry (see the discussion of the OPTION macro), and also 
specifies which option fields are not to be created for this process entry. 
Default: None. Specification optional. 



i 



48 OS/MFT and OS/MVT TCAM Programmer s Guide 



Format: The maximum length and type of data specified for each option field 
must correspond to the length and type specified by the OPTION macro that 
defines the field. The order in which the OPTION macros are specified must 
correspond to the values of data specified in this operand. 
Notes: A comma is used to: 

1. Delimit the data for each field; 

2. Indicate that no data is specified for the first or an intermediate field defined by 
an OPTION macro; 

3. Indicate that the OPDATA= operand is to be continued (if included immedi- 
ately preceding the right parenthesis — see below). 

The user must specify either data and a comma, or a comma alone for the first and 
each intermediate field (except the last) that is specified by an OPTION macro 
(with one exception — see the note below). A comma alone is coded if a field 
other than the last is not to be defined for this Une. If the last field is not to be 
defined, no data is coded for the field and the comma is also omitted. Framing 
characters (X or C and quotes) are not coded. 

When specifying option fields for a particular process entry, the user may omit the 
last several option fields defined by OPTION macros by merely closing the 
parentheses after the data for the final field he wishes to define. 

Example: 

Assume that four OPTION macros have been coded. If the user wants to specify 
all four fields for a particular station, Une, or application program, he would code 
the OPDATA= operand of the TERMINAL or TPROCESS macro: 

,OPDATA=( fieldl , field2, field3, f ield4 ) 

where fieldl , field! , fields , and field4 represent the actual initial data to be 
inserted into each of the four option fields. If only fieldl and field4 are to be 
implemented for this station, line, or application program, the user would code 

,OPDATA=( fieldl , , ,field4 ) 
If only fieldl , fieldl , and field3 are to be implemented, the user would code 

,OPDATA=( fieldl , f ield2, f ieldS ) 
If only fieldl is to be implemented, the user would code 

,OPDATA=( fieldl ) 

A message processed by an application program and then sent to a destination 
station must be handled by two sets of incoming and two sets of outgoing MH 
subgroups. Macros issued in the incoming subgroups handUng messages from a 
station update the option fields assigned to that station. Macros issued in the 
outgoing subgroups handling messages for the application program update the 
option fields assigned to the process entry associated with the GET or READ 
macro that obtains the messages for processing. Macros issued in the incoming 
subgroups handling messages from an application program update the option 
fields assigned to the process entry associated with the PUT or WRITE macro that 
returns messages from the application program to the MCP. Macros issued in 
outgoing subgroups handling messages being sent to a destination station update 
the option fields assigned to that station. (For a description of which Message 



Defining Terminal and Line Control Areas 49 



QBACK= 



J yes) 



Handler subgroups are required when there is an apphcation program, see 
Message Flow through a Message Handler in the chapter Designing a Mes- 
sage Handler . For a discussion of the interface between the MCP and the apphca- 
tion program see the introduction to Writing TC AM -Compatible Application 
Programs .) 

Because the operand field of a macro is limited to 255 characters, TCAM provides 
a facility to specify additional OPDATA= parameters if necessary. A comma 
placed as the last character of the OPDATA= operand — that is, 

,OPDATA=( data, data, . . .data, ) 

indicates a continuation of the OPDATA= operand. The next source statement 
would then be coded 

symbol TPROCESS OPDATA=( data, . . . ) 

where symbol is the process entry name as specified on the TPROCESS macro 
that specified the continuation. There is no limit (other than the number of option 
fields defined) on the number of continuation statements used. 



Function: Specifies whether the application program may issue the QRESET 
macro. 

Defauh: NO 

Format: QBACK=YES or QBACK=NO 

Notes: QBACK=YES causes the Queue Reset Executor module to be loaded into 
the MCP region and the allocation of a 258 byte work area in the MCP region. 
For information about TCAM's QRESET facility see Writing TCAM Compati- 
ble Application Programs. 



< 



50 OS/MFT and OS/MVT TCAM Programmer's Guide 



typename 



dcbname 



BUFSIZE=size 



LOGTYPE 



The LOGTYPE macro 

• initializes TCAM's logging facility; 

• may not be omitted if TCAM's logging facility is to be used for logging com- 
plete messages, and is unnecessary if segments are logged; 

• if coded, must be specified among the macros defining the terminal table and 
must not be the last such macro. 

The LOGTYPE macro initiaUzes TCAM's logging facility by specifying: 

1. The name of the data control block for the log data set, 

2. The buffer size used to handle messages to be logged, 

3. The location of the data set (on disk or in main storage). 

TCAM's logging facility is discussed in Using TCAM Service Facilities . The 
description of the LOG macro contains information on when LOGTYPE should 
be specified. 

A LOGTYPE macro must not be coded as the last macro defining the terminal 
table. No more than one LOGTYPE macro should be coded for a log data set. 



Name 


Operation 


Operands 


typename 


LOGTYPE 


dcbname, BUFSIZE=size 
,QUEUES=form 



Function: Specifies the name of the LOGTYPE macro and is the same 

as the typename operand of a LOG macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



Function: Specifies the name of the data control block for the log data set. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This name must be the same as the name of the DCB macro specifying the 

log data set. 



Function: Specifies the size of the buffers to be used to handle messages destined 

for the logging medium. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 



QUEUES=fonn 



Function: Specifies where the messages are to be queued while awaiting transfer 

to the logging medium. 

Default: None. This operand is required. 

Format: DR, DN, MO, MR, or MN. 



Defining Terminal and Line Control Areas 5 1 



Notes: DR specifies reusable disk queues. 

DN specifies nonreusable disk queues. 

MO specifies main-storage-only queues. 

MR specifies main-storage queues with reusable disk backup. 

MN specifies main-storage queues with backup on nonreusable disk. 

If MR or DR is specified, the original destination is automatically designated as 
the alternate destination for zone reorganization (see Reusable Disk Queues in 
the chapter Z)e/m/Aig the MCP Data Sets). Unlike the TERMINAL and 
TPROCESS macros, there is no ALTDEST= operand for the LOGTYPE macro. 

Maintaining Orderly Message Flow 

Thus far, this chapter has described how to define control areas needed by TCAM 
for line control, and how contact is estabUshed for the purposes of invitation and 
selection. This section describes how TCAM maintains an orderly message flow 
between the central computer and remote stations. 

Among the factors influencing the flow of messages within a TCAM system are 
message priority and queuing, transmission priority, and whether incoming logical 
messages are being handled. Message priority refers to the order in which 
messages are sent over a Une or to an application program. Priorities are assigned 
to individual messages by the user through his use of a priority field in the message 
header, a PRIORITY macro, and the type of queuing specified by the QBY= 
operand of the TERMINAL macro. Transmission priority refers to the relative 
order in which messages are sent to and received from a station or stations on a 
Une. The transmission priority (send, equal, or receive) for a nonswitched station 
is specified by the CPRI= operand of the line group DCB macro. For switched 
stations, CPRI=S (indicating send priority) must always be specified. If logical 
messages are being used, see Handling Logical Messages in the chapter 
Designing the Message Handler. 

These are not the only factors influencing TCAM message flow; two others are 
the manner in which calls are made between the computer and a switched station, 
and the system interval. The remainder of this chapter is devoted to discussions of 
all of these factors. 



Message Priority and Queuing 



To determine how to assign priorities to messages in a TCAM system, see the 
descriptions of the PRIORITY macro and of the LEVEL= operand of the 
TERMINAL and TPROCESS macros. In this section, we shall be concerned with 
a practical description of what message priority means in a TCAM system. 

This order depends upon three variables: 

• whether queuing is by line or by terminal; 

• the relative order in which the messages are received at the destination queue; 

• what priorities the messages are assigned. 

Messages whose destinations are stations may be queued by destination terminal 
or by destination line. The user specifies the type of queuing he wants by the 
QBY= operand of the TERMINAL macro. When outgoing messages are queued 
by line, one message queue is created for a line, and messages destined for all 
stations on the line are placed on this queue. (The incoming group of a Message 
Handler generally determines the destination of a message by a FORWARD 
macro.) Messages are taken off the queue and sent to stations on the line on a 



{ 



52 OS/MFT and OS/MVT TCAM Programmer's Guide 



first-ended first-out (FEFO) basis within priority groups. That is, messages on 
the queue that have a high message priority (as specified in the message header or 
assigned by a PRIORITY macro) are sent before messages having a low priority. 
When messages have the same priority, the one whose final segment arrived at the 
queue first will be sent out first, and the others will be sent out in the order in 
which their final segments arrived at the queue. (An example of queuing by line is 
given below.) 

Advantages of Queuing by Line 

• Queuing by line permits transmission of messages by priority on a line basis to 
stations on a multipoint nonswitched line; that is, all messages of a given 
priority on the queue are transmitted before any messages of a lower priority, 
whether or not the higher-priority messages are destined for two different 
stations on the line. 

• Queuing by line takes less storage space than queuing by terminal. If queuing is 
by line rather than by terminal, at least 65 bytes are saved for each station after 
the first on a line, plus about 28 bytes per station after the first for each priority 
level specified beyond one. 

Disadvantages of Queuing by Line 

• Queuing by line results in switching between stations on the line rather than 
maintaining connection with a station. 

When outgoing messages are queued by terminal, one message queue is created 
for each station on a line. All messages queued for a given station are sent before 
any messages queued for other stations on the line. Messages on a queue are sent 
to a station on first-ended first-out (FEFO) basis within priority groups. The first 
message on a queue is the message whose last segment arrived at the queue before 
the last segment of any other message arrived at the queue. High-priority mes- 
sages are sent before low-priority messages; when two messages on a queue have 
equal priority, the one whose final segment arrived at the queue earUest is sent 
first. For a multipoint line, the relative order in which queues of messages are 
transmitted is also determined on a FEFO basis; the queue containing the message 
whose incoming transmission over the line was completed first will be sent before 
any other queue for a station on that line. 

Queuing by terminal must be specified for switched stations and for buffered 
terminals. If switched stations were queued by line, a station that called in would 
receive not only its messages, but those for all other stations in the line group as 
well. 

Messages destined for an application program are placed on a queue for that 
program and are removed from it as if they were messages queued by terminal; 
that is, they too are sent to the application program on a FEFO basis within 
priority groups. 

Advantages of Queuing by Terminal 

• Queuing by terminal permits transmission of messages by priority on a station- 
by-station basis. All messages in a given queue for a station on a Une are 
transmitted before any messages in other queues for the remaining stations on 
the line are transmitted, whether or not the other queues contain messages 
having priorities higher than those for the messages being transmitted. Thus, 
messages for the same station are sent as a group. 



Defining Terminal and Line Control Areas 53 



Disadvantages of Queuing by Terminal 

• Queuing by terminal takes more storage space than does queuing by line. 

The orders of sending described above are disrupted when a message segment for 
which the INITIATE macro has been executed arrives at a destination queue; such 
a segment is treated as if it were a completed message having the highest priority 
on the queue, and it is sent before any other message on that queue is sent. In 
addition, no message on the queue may be sent until all segments of the message 
for which INITIATE was executed have arrived at the queue and been sent to 
their destination. (See the description of the INITIATE macro.) 

Examples: 

A multipoint nonswitched Une on which are located the following three terminals 
(each name given corresponds to the symbol field of the TERMINAL macro 
defining that terminal): NYC, BOS, RAL. Nine messages arrive from various 
remote stations, or perhaps from an application program; these messages are to be 
routed to the three terminals on this line. Messages 1 through 9 are completely 
enqueued on a destination queue in the following temporal order: 

1 for NYC 

2 for NYC 

3 for BOS 

4 for RAL 

5 for RAL 

6 for BOS 

7 for NYC 

8 for RAL 

9 for RAL 

Assume first that queuing is by line, and that all messages have the same message 
priority. In this case, the messages are sent out in the same order that they were 
enqueued on the destination queue for the line: 1, 2, 3, 4, 5, 6, 7, 8, 9. 

Now, assume that queuing is by terminal and that all nine messages have the same 
message priority. In this case, the messages are queued 

. 1,2, 7 for NYC 

• 3, 6 for BOS 

. 4,5, 8, 9forRal 

and are sent out: 1, 2, 7, 3, 6, 4, 5, 8, 9. 

Next, assume that messages 1, 5, and 9 have a message priority of 10; that mes- 
sages 2, 4, and 7 have a message priority of 30; and that messages 3, 6, and 8 have 
a message priority of 60. 

The messages will be queued by line or by terminal (depending upon which is 
specified in the TERMINAL macros) as if they all had the same priority. The 
order in which they are sent, however, differs from the case in which all messages 
have the same priority. 

If queuing is by line, the messages are sent in the order 3, 6, 8, 2, 4, 7, 1, 5, 9. 

If queuing is by terminal, the messages are sent in the order 2, 7, 1, 3, 6, 8, 4, 5, 9. 



{ 



54 OS/MFT and OS/MVT TCAM Programmer s Guide 



Transmission Priority 



Note the following points: 

• When messages for stations on a multipoint line are queued by terminal, the 
order in which the groups of messages queued for the individual stations on the 
line are transmitted depends on when the last segment of the first message on 
each individual queue arrives at the queue. In the above example the last 
segment of the first message on the queue for NYC arrived at its queue before 
the last segment of the first message on the queue for BOS arrived at its queue, 
and the last segment of the first message on the queue for BOS arrived at its 
queue before the last segment of the first message arrived on the queue for 
RAL. Therefore, all messages queued for NYC are transmitted before any 
message queued for BOS is transmitted, and all messages queued for BOS are 
transmitted before any message queued for RAL is transmitted. 

• When messages for stations on a multipoint Une are queued by terminal, the 
order in which the messages queued for an individual station are transmitted is 
determined by two rules: 

1 . All messages having a high message priority are transmitted before any 
message having a low message priority is transmitted. 

2. When messages have equal message priorities, the message whose final 
segment arrived at the queue first is sent first, the message whose final 
segment arrived at the queue second is sent second, etc. 

When these two rules are in effect, messages are said to be sent out on a 
first-ended-first-out (FEFO) basis within priority groups. 

Messages for stations on point-to-point lines, whether switched or non- 
switched, are also transmitted on a FEFO basis within priority groups. 
(Remember that switched Hnes are considered to be point-to-point, and that 
queuing by terminal should always be specified for switched lines.) 



Transmission priority refers to the relative order in which messages are sent to and 
received from the stations on a line. Transmission priority is specified on a Une 
group basis by the CPRI= operand of the line group DCB macro. 

Transmission priority has a different meaning for each of the following four 
configurations of stations: 

1 . Polled stations (unbuffered) on a nonswitched point-to-point or multipoint 
line; 

2. Buffered polled stations on a nonswitched multipoint line; 

3. Contention stations on a nonswitched point-to-point line; 

4. Stations on a switched Une. 

TCAM considers a buffered station to be one for which the BFDELAY= ope- 
rand of the TERMINAL macro is coded. A special scheme for transmitting 
outgoing messages is implemented for such a station (see the description of the 
BFDELAY= operand of TERMINAL). A station may be defined as buffered 
using the BFDELAY= operand even though no delay is ever taken. 

Transmission Priority for Nonswitched Polled Stations 

For such stations, the user may specify that sending has priority over receiving (by 
coding CPRI=S in the line group DCB macro), that receiving has priority over 
sending (CPRI=R), or that sending and receiving have equal priority (CRPI=E). 
The meaning of these priorities depends upon whether the line is being polled 
under the control of the TCAM program polUng scheme, or under the control of 
the Auto PoU hardware feature. 



Defining Terminal and Line Control Areas 55 



TCAM Program Poll: When this scheme is used, TCAM polls all stations 
designated as active in the invitation Ust for an active line. In poUing, TCAM 
begins with the first active station in the Ust, and invites it to enter a message by 
sending its polling characters. If the station has a message to enter, it responds by 
entering the message, following which TCAM polls it again. 

If receiving has priority over sending, the cycle of poUing and entering is repeated 
until the first station has no more messages to enter. When TCAM receives a 
negative response to polling from the first active station in the list, it proceeds to 
the second active station in the Ust, and poUs it. TCAM continues to poU the 
second station until the station indicates that it has no more messages to enter; 
TCAM then poUs the third station. TCAM proceeds through the Ust in this 
fashion until a negative response to polling is received from the last station in the 
list. At this time, TCAM observes the invitation delay specified by the INTVL= 
operand of the line group DCB macro, or by a POLLDLAY operator command. 
During the invitation delay, outgoing messages are sent to stations on the line in 
the order described in Message Priority and Queuing . (If the computer has no 
messages to send to stations on the line at this time, the invitation delay is ob- 
served nevertheless.) Outgoing messages are sent until the delay expires or the 
destination queues for stations on the line are empty. Upon expiration of the 
delay, outgoing message transmission ends after the current message is sent, 
regardless of whether any messages remain queued. As soon as outgoing message 
transmission ceases, polling and incoming message transmission resume, and the 
cycle is repeated. It is important to note that if no invitation delay is specified, 
outgoing message transmission does not occur. If an invitation delay is specified, 
it must be long enough to accommodate the expected density of outgoing message 
traffic; too short a delay causes outgoing messages to accumulate on the destina- 
tion queues for Unes or stations in a line group. 

If receiving and sending have equal priority, polling and incoming message traffic 
proceed without interruption until the end of the invitation Ust is reached. Then 
any outgoing messages are sent to stations on the Une in the order described in the 
Message Priority and Queuing section. Once outgoing transmission begins, it 
continues until aU messages queued for stations on the line have been sent, 
regardless of whether the user has specified an invitation delay. When all mes- 
sages for stations on the line have been sent, polling and incoming message traffic 
resume. Note that, in contrast to the case where receiving has priority over 
sending, outgoing message transmission occurs whether or not an invitation delay 
is specified and regardless of the specified length of the delay. 

If sending has priority over receiving, any outgoing messages are sent to a station: 

1. Each time a negative response to pofling is received from a station; 

2. Each time an EOT is received from a station, indicating that a complete mes- 
sage has been received; 

3. Each time the end of the invitation Ust is reached. 

Outgoing messages are sent in the order described in the Message Priority and 
Queuing section. Once outgoing message transmission begins, it continues until 
all messages queued for stations on the line have been sent. Note that when 
sending has priority over receiving, outgoing transmission can occur after each 
station is polled, rather than only after a complete polling pass. 

Auto Poll: For lines poUed under the control of the Auto Poll hardware feature, 
the scheme given above is sUghtly modified. 



( 



56 OS/MFT and OS/MVT TCAM Programmer's Guide 



If receiving has priority over sending, messages are sent to stations on the line 
during the invitation delay. However, if no messages have been queued for 
stations on the line by the time the end of the invitation list is reached, no invita- 
tion delay is observed. 

If receiving and sending have equal priority, there is no difference between 
autopoUed and other polled lines. 

If sending has priority over receiving, outgoing messages are sent over autopoUed 
lines: 

1. Each time an EOT is received from a station, indicating that a complete mes- 
sage has been received; 

2. Each time the end of the invitation list is reached. 

Transmission Priority for Nonswitched Polled Stations Using TCAM^s Buffering 
Feature 

The IBM 2740 Model 2 contains a hardware buffer (and a message to the 2740 
Model 2 must fit within this buffer); the IBM 2770 on a multipoint line contains 
two hardware buffers. Messages to these stations fill the buffers at line speed. A 
message is read from the buffer to the terminal output device at the speed of the 
output device. This improves line utilization, since the Une is occupied with 
individual stations for short periods of time. If a buffered station is addressed 
before the buffer has emptied, a negative response is returned and the station 
must be selected again later. A message to be entered from a buffered station is 
first entered into the buffer from the input component (at the speed of the input 
device). When the buffer is filled or the message is entered, the message is trans- 
mitted to the CPU at line speed the next time the station is polled. 

TCAM sends to an IBM 2740 Model 2 a message at a time and to an IBM 2770 
until its buffer space is filled. The 2740 Model 2 accepts messages; thus, a block 
of data to the 2740 Model 2 must be equivalent to a whole message. To prevent 
TCAM from trying to send a message to a 2740 Model 2 while the hardware 
buffer is still emptying the previous message and thus wasting time on the line, 
TCAM allows the user to specify (in the BFDELAY= operand of the 
TERMINAL macro) the number of seconds to delay before sending each message 
after the first to a 2740 Model 2. The time specified should be the average time 
needed to empty the hardware buffer (the BFDELAY= operand must be speci- 
fied for the IBM 2770 also; see BSC device-dependent considerations in the 
SQCiiontiil&d Sending Operations in Appendix G). While this interval is in 
effect, TCAM can be sending messages to other stations on the line, thereby 
utiUzing the Une more efficiently. 

Thus, when BFDELAY= is specified for the 2740 Model 2 on a multipoint line, 
messages are sent to stations on the line on a message-by-message basis: the first 
message is sent; if there are messages queued for other stations on the line, they 
are sent; subsequent messages are sent as stations become available. For the 2740 
Model 2 to become eligible to accept another message, the time interval specified 
by the BFDELAY= operand of its TERMINAL macro must have elapsed. For 
information on how to determine the correct interval and restrictions on coding 
BFDELAY=, see the description of this operand in the TERMINAL macro. 

When a STOPLINE operator command, a QTAM STOPLN macro, a SYSCLOSE 
operator command, or an MCPCLOSE macro specifying a quick closedown is 
executed, transmission on a line to stations using TCAM's buffered-terminal 
support is not stopped until all messages being sent to stations on the line at the 



Defining Terminal and Line Control Areas 57 



time the command or macro is executed have been completely sent and all inter- 
vals specified by the BFDELAY= operand of the TERMINAL macros for 
stations on the line have been observed. 

For TCAM's buffering feature to work properly for the IBM 2740 Model 2, 
queuing by terminal and either equal or send priority must be specified in the 
TERMINAL and Une group DCB macros. 

Transmission Priority for Nonswitched Contention Stations 

The following can be nonswitched contention stations: the IBM 2740 Basic, the 
IBM 2780, the IBM 2770, World Trade (WTTA) terminals, and the IBM 
System/360, System/360 Model 20, and 1 130 Computing System. For non- 
switched contention stations, either equal or send priority may be specified. The 
way in which equal priority works is device-dependent, and is explained in 
Appendix G. 

Send priority is similar for all these types of stations. If send priority is specified, 
messages may be entered at the station whenever the line is idle. Whenever a 
message is queued for sending, TCAM checks to see whether a message is being 
entered by the station; if so, the computer waits until an EOT control character is 
received and then sends all messages queued for the station. If no message is 
being entered, the computer sends all queued messages immediately after check- 
ing. After sending all messages, the computer is ready to receive messages from 
the station. The invitation Ust for the Une may consist of a dummy entry (see the 
description of the INVLIST macro). 

For equal priority for the devices listed above, see Appendix G: Device- 
Dependent Considerations. f\ 

i 

When a BSC device is in contention with the CPU, TCAM defers to the BSC 
device for control of the line. However, when a start-stop device has a message to 
enter, and it is in contention with the CPU, the start-stop device loses that mes- 
sage (a Message Handler that includes the SEQUENCE macro can indicate when 
a message is lost to the system). 

Transmission Priority for Switched Stations 

For switched stations on a start-stop line, CPRI=S must be specified in the line 
group DCB macro. For BSC switched stations, CPRI=S or E may be specified. 

The relative order in which messages are sent to and received from a station on a 
switched line depends upon whether or not the station is a BSC station. 

When a non-BSC station calls the computer, once the connection is established, 

the station begins to enter any messages it may have ready for the computer. 

Before it can accept messages, the station caUing in must identify itself to the 

computer by an origin field, verified by an ORIGIN macro, in a message header. 

If the station does not identify itself, upon receiving a negative response to 

invitation, the computer sends the station any messages queued for the line entry 

for this Une. If no messages are queued for the line entry, or if there is no Une 

entry, the computer breaks the Une connection upon receiving a negative response 

to invitation, thereby making the line available for other caUs. Once the station 

identifies itself, it is eUgible to accept messages. If any messages were queued for 

the station at the time it identified itself, the station accepts these messages as j 

soon as possible; no further messages may be entered at the station until the i 

queued messages are sent. Messages are sent by the computer according to the 



58 OS/MFT and OS/MVT TCAM Programmer's Guide 



priority scheme outlined in the section Message Priority and Queuing . If the 
destination queue for the station was empty at the time the station identified itself, 
or once the queue becomes empty during this call, subsequent messages are sent 
to the station as soon as possible after they are placed on the destination queue. 
That is, whenever a message is completely enqueued on the previously empty 
destination queue during this call, TCAM checks to see whether a message is 
being entered by the station; if so, the computer waits until the message has been 
completely received, and then sends all messages queued for the station. After 
sending all messages, the computer invites the station to enter messages. When 
the last incoming message is received and no further messages appear on the 
destination queue for the station, the computer breaks the line connection, making 
the Une available for new calls. 

When the computer calls a non-BSC station, the computer sends all messages 
queued for the station before the station enters any messages (except that when 
the time specified in either the CLOCK= or the CINTVL= operand of the 
TERMINAL macro expires, TCAM invites the station to enter messages before it 
sends messages queued for the station). Messages are sent by the computer 
according to the priority scheme described in the section Message Priority and 
Queuing Once all queued messages have been sent, or if the qiieue was empty, the 
station begins entering any messages it may have ready. If a message is enqueued 
for the station after the station begins entering messages, TCAM sends the 
message as soon as the message currently being received from the station has 
finished, as described above. When the station indicates that it has no more 
messages to enter, and no further messages appear on the destination queue, 
TCAM breaks the Une connection, rendering the line available for new calls. 

See Appendix G. Device-Dependent Considerations for the transmission priority 
/ for: 

• 2740 Communications Terminal on a switched line; 

• Switched BSC stations; 

• Switched TWX stations. 

CaUs Between the Computer and a Switched Station 

On a line group basis, the order in which messages on a switched line are sent and 
received depends upon whether the computer dials a station or a station dials the 
computer, and upon when calls are made. 

In a TCAM system, a station may call the CPU on a line in its own line group that 
has a relative line number equal to or greater than the line to which the calUng 
station is assigned. When a station dials the computer, the response may be either 
manual, or automatic if it is equipped with the Auto Answer feature. 

If these requirements are satisfied, and if the line is not currently connected to 
another station, a connection is estabUshed each time the station dials the number 
associated with the line. If the Une is connected to another station when a station 
dials its number, the diaUng station receives a busy signal and must try again later. 
Once contact is successfully established between station and computer, message 
transmission occurs according to the scheme described in the section 
Transmission Priority for Switched Stations . 

If the computer is equipped with the Auto CaU feature, it may dial switched 
stations. For the computer to dial a switched station the station's telephone 
number must be entered in the DIALNO= operand of its TERMINAL macro 
(and the computer must be equipped with the Auto CaU feature). If CLOCK= is 

Defining Terminal and Line Control Areas 59 



coded for the TERMINAL macro, the computer dials the station only at the time 
specified by CLOCK=, and this is the only time at which the station may receive 
messages from the computer. If CLOCK= is specified, the station is invited to ( 

enter messages before TCAM sends messages queued for the station. 

If CLOCK= is not coded, an attempt is made to call the station whenever a 
message is completely received and enqueued in the previously empty destination 
queue for that station. (A destination queue is considered to be *'empty" when it 
contains no completely received, but as yet unsent, messages.) 

If the CINTVL= operand of the TERMINAL macro provides an interval, and the 
station does not call in and is not called during this time, TCAM calls the station 
at the end of the interval. (When the station calls in or is called during the speci- 
fied interval, the interval begins again.) When the time specified by CINTVL= 
expires, the station is invited to enter messages before TCAM sends those mes- 
sages queued for the station. If the specified interval has not expired, TCAM 
sends all messages queued for the station before the station is invited to enter its 
messages. 

When the first message arrives at the previously empty destination queue for a 

station (if CLOCK= is not coded), or the time specified by CLOCK= or 

CINTVL= is reached, the computer attempts to dial the station over the line 

specified by the RLN= operand of the TERMINAL macro for the station. If this 

line is currently being used by another station, the computer attempts to place the 

call over the line whose relative line number is one greater than that specified for 

this station. If this line is also being used by another station, the computer checks 

the Une whose relative line number is one higher than that for the Une just 

checked; this procedure is repeated until an available line is found, or until the line | 

having the highest relative line number in this line group is checked and found to i 

be in use. If the line with the highest relative Une number in the group is in use, 

the call is delayed until a line becomes available, at which time it is sent. If more 

than one waiting call is eUgible to be made over a line that has just become 

available, TCAM decides which call to make according to a priority scheme 

described below. Once the connection between computer and station is estab- 

Ushed, transmission occurs in accordance with the scheme described in the section 

Transmission Priority for Switched Stations. 

TCAM's caUing scheme is designed to take advantage of AT & T's Wide Area 
Telephone Service (WATS). If WATS is used, care should be taken to arrange the 
lines in a switched line group to take full advantage of the TCAM calling scheme. 
Lines should be arranged according to increasing area of WATS coverage, with 
the line covering the smallest area being assigned relative line #1, and the line 
covering the largest area being assigned the highest relative line number in the 
group. (The way in which lines in a line group are assigned relative line numbers 
is described in DD Statements for a Line Group in the chapter Defining the 
MCP Data Sets .) It is most economical for stations to be assigned to lines whose 
WATS coverage extend to their area and no farther; in no event should stations be 
assigned to a line whose coverage does not extend to their location. 

When a call cannot be made because all available lines in the Une group are busy, 

TCAM queues the request and defers the call until a suitable Une is available. If a 

line becomes available, and if there is more than one call that could be made over 

the line according to the rules described above, TCAM determines which station ^ 

wiU be caUed first by applying the following principles: 1 



60 OS/MFT and OS/MVT TCAM Programmer's Guide 



The System Interval 



1. A station whose destination queue contains one or more messages having 
nonzero message priorities is called before a station whose destination queue 
contains only messages to which no message priority was assigned (that is, 
messages having zero priority). A station whose destination queue contains no 
complete messages is treated like a station whose queue contains only zero- 
priority messages {see 3 below). 

2. A station having a high-priority message on its destination queue is called 
before a station having low-priority messages on its destination queue. If the 
highest-priority messages on the queues for two eUgible stations are equal in 
priority (and if this priority is not zero), the time at which the last segments of 
the high-priority messages were enqueued determines which station is called; 
the station whose destination queue received the last segment of its highest- 
priority message first is called first. 

3. Among stations having only zero-priority messages on their destination queues, 
TCAM calls the station whose relative Une number is equal to, or closest to but 
lower than, the relative Une number of the available line. Among stations 
having only zero-priority messages on their destination queues and having the 
same relative Une number, TCAM caUs the eligible station whose queue was 
first to receive a complete message. 

4. Among stations whose queues contain no complete messages, TCAM calls the 
eUgible station for which the caU has been deferred the longest (this principle is 
applicable only for stations whose TERMINAL macro specifies CLOCK= or 
CINTVL=). 

Note that a strict WATS priority scheme for deferred caUs is observed only among 
stations whose destination queues contain only messages having zero priority. If 
relative line #6 becomes avaUable and caUs have been deferred for a station 
assigned to relative line #1 and for a station assigned to relative line #6, and if the 
queue for the station assigned to relative line #1 contains the highest-priority 
message, this station wiU be called before the other, even though it would be more 
economical from a WATS standpoint to caU the station assigned to relative line 
#6. (See Principle #2 above.) If the queues for both stations contain only zero- 
priority messages, a WATS priority scheme wiU be applied, and the station 
assigned to relative line #6 wiU be called first. (See Principle #3 above.) 

If the computer dials a station and gets a busy signal, it is treated as an error 
condition. The station's number will be dialed twice more; if no connection is 
established in three attempts, TCAM sets the selection error bit in the message 
error record, and the message is lost unless a REDIRECT or HOLD macro is 
executed for it in the outmessage subgroup. (The text error bit in the message 
error record may also be turned on — see the description of this bit in Appendix 
B.) 

Once the connection between the computer and a switched station is established, 
transmission occurs according to the scheme described in the section 
Transmission Priority for Switched Stations . 



Message flow is vitally affected by the system interval , a period of time specified 
by the INTVAL= operand of the INTRO macro. The INTERVAL operator 
command teUs TCAM to begin the system interval. When this message is re- 
ceived, each leased line to polled stations is "frozen" that is, receiving and sending 
of messages cease on it) at the start of its current polling pass. When all leased 
lines are inactive, the system interval commences. Lines to switched stations and 
local lines are left active; stations on such lines may stiU enter and accept mes- 
sages. A SYSINTVL operator command may be entered to change the duration 



Defining Terminal and Line Control Areas 61 



of the system interval. If this message is entered while a system interval is in 
effect, it does not change the duration of the current interval, but changes subse- 
quent intervals. 

The system interval is used to minimize unproductive polling, to minimize CPU 
meter time, and to synchronize polling on the polled lines in the system. In 
general, if there is no traffic on any Une in the TCAM system, the OS supervisor is 
given control to dispatch the next concurrent job. 



< 



62 OS/MFT and OS/MVT TCAM Programmer s Guide 



Structure of a Buffer 



Defining Buffers 



Messages entering a TCAM network are read into buffers, which are user-defined 
areas of main storage used for handUng, queuing, and transferring message 
segments between ail Hnes and queuing media, and between queuing media and 
appUcation-program work areas. (A message segment is that portion of a message 
contained in one buffer.) A buffer has two parts, one containing control informa- 
tion (the buffer prefix ) and the other containing all or part of the message. 
Buffers must be at least 35 bytes, and may be no larger than 65535 bytes. 



To provide the best dynamic buffering capability and use of main storage, the 
TCAM network has one buffer unit pool containing buffer units of one size. 
Buffer units are the basic building blocks from which buffers are constructed. 

The size of a unit is specified by the KEYLEN= operand of the INTRO macro of 
an MCP, and the number of units in the pool is equal to the sum of the numbers 
specified by the LNUNITS= and MSUNITS= operands of INTRO. For internal 
management purposes, 12 bytes are added by TCAM to the user-specified unit 
size. Thus, if a user specifies a unit size of 60 bytes (KEYLEN=60), the size of 
the unit becomes 72. The user should not concern himself with the extra 12 bytes 
when defining buffers. 

If .the sum of the number of bytes specified by the KEYLEN= operand plus 12 
bytes is not evenly divisible by eight, TCAM adds enough bytes to each unit to 
make its tqtal length divisible by eight. This is done so that units that are contigu- 
ous in main storage always start on a doubleword boundary. 

The size of a buffer for a line group is specified by the BUFSIZE= operand of the 
DCB macro defining the line group data set for that group. Each line group may 
use buffers that differ in size from those assigned to other line groups. 

By coding the BUFSIZE= operand of the TERMINAL macro, the user may 
override the buffer size specified in the line group DCB macro on a station-by- 
station basis, for outgoing messages only. 

By linking an appropriate number of units, TCAM constructs buffers containing a 
number of bytes at least as great as that specified by the BUFSIZE= operand of 
the DCB macro for a given line group. (The 12 bytes added to each unit by 
TCAM should not be considered in defining BUFSIZE=; the user should consid- 
er only the number of bytes he specified in the KEYLEN= operand of the INTRO 
macro.) For example, if the user specified KEYLEN=60 in the INTRO macro and 
BUFSIZE= 120 in a line group DCB, TCAM links together two units in building 
buffers for that line group. If, however, KEYLEN=60 and BUFSIZE= 100 is 
coded, TCAM will still link two units, but the last 20 bytes of the second unit 
cannot be used, and main-storage space is wasted. If KEYLEN=60 and 
BUFSIZE=40 is specified, the last 20 bytes of the first (and only) unit assigned 
are wasted. 

There are two types of logical buffers, header buffers and text buffers. A header 
buffer is a buffer that contains all or any part of a message header. A text buffer 
contains message text only. 



Defining Buffers 63 



A buffer prefix is a control area contained within each physical buffer of the 
system. The user must allow room for the buffer prefix in defining buffers. 
TCAM fills in the buffer prefix area with buffer control information. 

If only one buffer is used to contain a message, the buffer prefix occupies the first 
30 bytes of the buffer. If more than one buffer is used to contain a message, a 
30-byte buffer prefix occupies the beginning of the first buffer, and a 23-byte 
buffer prefix occupies the beginning of each subsequent buffer assigned to the 
message. 

Thus, there are two kinds of control areas associated with buffers. The 12-byte 
control area associated with each buffer unit is assigned automatically by TCAM 
and need be of no concern to the user when defining buffers. The 30-byte 
(header) or 23-byte (text) buffer prefix assigned to each buffer is of concern to 
the user, who must allow for this area in defining the size of his units. Each unit 
must be large enough to contain the larger prefix plus five bytes (35 bytes) and 
may be no larger than 255 bytes. Obviously, the second and subsequent buffers 
will contain more bytes of actual message than will the first buffer, since their 
prefixes are seven bytes shorter than that of the first buffer. 

Figure 2 shows how two buffers assigned to a line group would look if the user 
specified KEYLEN=60 and BUFSIZE=120. 



12 Bytes 
Buffer Unit 
ConlTol 



30 Bytes 
First Buffer 
Prefix Area 



30 Bytes 
Message Header 
and Text 



Unit 1 



12 Bytes 
Buffer Unit 
Control 



60 Bytes 
Message Header 
and Text 



Unff2 



> Buffer #1 



12 Bytes 
Buffer Unit 
Control 



23 Bytes 

Subsequent Buffer 
Prefix Area 



37 Bytes 
Message Header 
and Text 



Unit 1 



12 Bytes 
Buffer Unit 
Control 



60 Bytes 
Message Header 
and Text 



Unit 2 



> Buffer #2 



{ 



Figure 2. Two Buffers Assigned to a Line Group; KEYLEN=60 and BUFSIZE=120 



64 OS/MFT and OS/MVT TCAM Programmer's Guide 



The Buffer Unit Pool 



Notice that each buffer is composed of two units linked together, and that the two 
buffers are also linked together. Each unit is 72 bytes long (the 60 bytes specified 
by KEYLEN= plus a 12-byte unit control area added by TCAM). In defining 
BUFSIZE for the line group, only the 60 bytes specified by the user were consid- 
ered. 

Remember that 

• a buffer is composed of one or more buffer units; 

• each buffer unit must be at least 35 bytes (not counting the 12-byte control 
area added by TCAM) and may be no larger than 255 bytes (not counting the 
unit control area); 

• each buffer must be at least 35 bytes (minimal size of one unit) and may be no 
larger than 65535 bytes. 



One buffer unit pool is defined for the Message Control Program. This single 
pool contains a number of buffer units equal to the sum of the numbers specified 
by the LNUNITS= and MSUNITS= operands of the INTRO macro. The total 
number of units in the unit pool must not exceed 65535. 

When message traffic is in progress, a unit in the unit pool may be in any one of 
three states: 

1 . If a main-storage message-queues data set is specified, some units are 
assigned to main-storage message queues; 

2. Some units are linked to form buffers assigned to line or application pro- 
grams to handle data transfer; 

3. Some units are assigned to an available-unit queue , where they remain until 
linked to form a buffer or until assigned to a message queue. 

Figures 3 and 4 show allocation of the units in a unit pool. Figure 3 illustrates 
how units are allocated when the user specifies main-storage message queuing 
with or without backup on reusable or nonreusable disk (see Defining the MCP 
Data Sets for a discussion of main-storage message queuing). 

The first block in Figure 3 depicts the unit pool just after storage has been allocat- 
ed for it, when main-storage queuing is specified. The pool consists of a number 
of units equal to the sum of the LNUNITS= and MSUNITS= operands of 
INTRO. Each unit has a length equal to the number of bytes specified by the 
KEYLEN= operand of INTRO, plus 12 bytes. All units are assigned to the 
available-unit queue. 

The second block in Figure 3 shows how the pool looks just before selection and 
invitation begin. A certain number of units have been linked to form buffers, 
which are assigned to line groups and application programs to handle initial send 
and receive operations (the number of buffers assigned is specified for Une groups 
by the BUFIN= and BUFOUT= keyword operands of the line group DCB macro, 
and for application programs by the BUFIN= and BUFOUT= operands of the 
PCB macro). All other units are still in the available-unit queue. 

The third block in Figure 3 illustrates the situation when normal message traffic is 
in progress. Some units are in line and application-program buffers; others are in 
main-storage message queues; the remainder are in the available buffer queue. 
The arrows represent the normal limits in size of the fraction of the unit pool that 
can be assigned to line and application-program buffers or to main-storage 
message queues after selection or invitation has begun. The number of units 



Defining Buffers 65 



assigned to main-storage message queues may never exceed the number specified 
by the MSUNITS= operand of INTRO. The number of units assigned to line and 
application-program buffers will not ordinarily exceed the number specified by the 
LNUNITS= operand of INTRO. However, under exceptional conditions (for 
example, when main-storage queuing with backup on disk is specified, and there is 
a peak period of line activity with low main-storage queue activity and high disk 
activity), the number of units assigned to line and application-program buffers 
may exceed the number specified by LNUNITS=, if the number of units required 
is available in the available-unit queue. 

Figure 4 illustrates how units are allocated when the user has specified disk 
queuing only for his message queues data set. 

The first block in Figure 4 depicts the unit pool just after storage has been allo- 
cated for it. The pool consists of a number of units equal to that specified by the 
LNUNITS= operand of INTRO. All units are assigned to the available-unit 
queue. 

The second block in Figure 4 shows how the pool looks just before selection or 
invitation commences. A certain number of units have been linked to form 
buffers, which are assigned to line groups and application programs to handle 
sending and receiving operations. All other units are on the available-unit queue. 

The third block in Figure 4 illustrates the situation when normal message traffic is 
in progress. Each unit in the pool is either assigned to a line or application- 
program buffer or assigned to the available-unit queue. The arrows illustrate the 
limit in size of the fraction of the unit pool that may be assigned to line buffers 
after selection or invitation has begun. All units on the available-unit queue may 
be assigned to line buffers. 

Buffers are not always available to be assigned to lines; for example, when TCAM 
does a Read operation for a data set residing on disk, a buffer is reserved to hold 
the record read from the disk. 

Buffers assigned to TCAM application programs differ from those assigned to the 
MCP in the way in which they are defined and in the manner in which they are 
allocated. For additional information on such buffers, see Defining Buffers for 
the Application Program in the chapter Writing TCAM -Compatible Application 
Programs , 



/I 



( 



66 OS/MFT and OS/MVT TCAM Programmer s Guide 



Initially: 



Unit Pool 



Assigned by 
LNUNITS= 

Assigned by 
MSUNITS= 




) Available -Unit 
Queue 



Just Before Selection 
or Invitation • 



Unit Pool 



Assigned by 
LNUNITS= 



Assigned by , 
MSUNITS= 




Units in Line Buffers 



> Available-Unit Queue 



Norma I 
Traffic : 



Unit Pool 



--- (BssJ' 



Assigned by 
MSUNITS= 



^ 



± 



Units in Line Buffers 



«. > Available-Unit Queue 



Units in Main-Storage 
Message Queue 



Figure 3. Unit Allocation when Main-Storage Queuing (with or without Backup on Disk) is 
Specified 



Initially: 



Unit Pool 



Assigned by 
LNUNITS= 



Available-Unit 
Queue 



Just Before Selection 
or Invitation: 



Unit Pool 



Assigned by 
LNUNITS= 




Norma I 
Traffic: 



Assigned by 



Units 
Originally in 



Unit Pool 



J Units in Line Buffers 



Available-Unit Queue 



LNUNITS= < Line Buffers 






Units in Line Buffers 



Available-Unit Queue 



Figure 4. Unit Allocation when Disk-Only Queuing is Specified 



Defining Buffers 67 



< 



Buffer Definition Checklist 

A checklist of the TCAM macro operands directly involved in MCP buffer 
definition follows. (A similar checklist for defining application-program buffers is 
contained in the chapter Writing TCAM-Compatible Application Programs .) The 
macros to which the operands belong are described in detail elsewhere in this 
publication. The user should first scan the checklist to give himself a general idea 
of what is involved in defining TCAM buffers, and then read the next section, 
which contains guidelines for coding many of these operands. Finally, the check- 
list may be used during actual buffer definition to assure that all applicable 
operands are coded. For information on maximum and minimum values and 
defaults, see the operand description for the. associated macro. 



Macro 
INTRO 



Operand 
KEYLEN=integer 



Line Group 
DCB 



LNUNITS=integer 



lBUFSIZE=integerJ 



Description of Function and Comments 

Specifies the length in bytes of a buffer unit. The unit as it exists in 
the unit pool is equal in length to the number of bytes specified by 
KEYLEN= plus a 12-byte control area added by TCAM. TCAM 
begins each unit on a doubleword boundary. In order to conserve 
main storage, the following formula can be used as a guideline in 
determining a value for KEYLEN= : 

KEYLEN=8x-12 

where x is any integer between 6 and 35, inclusive. A buffer unit 
must be large enough to accommodate the larger of: 

(a) a header prefix (30 bytes) plus the maximum number of reserve 
characters specified for the first buffer by the RESERVE = 
operand of any line group DCB macro or PCB macro plus 5 
bytes, or 

(b) a text prefix (23 bytes) plus the maximum number of reserve 
bytes specified for buffers other than the first by the 
RESERVE = operand of any line group DCB macro or PCB 
macro plus 5 bytes. 

Specifies the number of buffer units in the unit pool that may build 
line buffers and buffers to handle appUcation-program traffic. The 
sum of LNUNITS= plus MSUNITS= must not exceed 65535. 

Specifies the size of buffers to be used for ail lines in this line group. 
The size specified here may be overridden on a station basis for 
outgoing messages by means of the BUFSIZE= operand of the 
TERMINAL macro. The maximum number of units per buffer is 

255. 



[BUFIN=integer] 

[BUFOUT=integer] 

[BUFMAX=integer] 



Specifies the number of buffers assigned initially for receiving 
operations for each line in the line group. 

Specifies the number of buffers to be assigned initially for sending 
operations for each line in the line group. 

Specifies the maximum number of buffers allocated to a line at one 
time. If this operand is omitted, the larger of BUFIN= and 
BUFOUT= is assumed. 



Defining Buffers 69 



Macro 



Operand 



Description of Function and Comments 




Specifies whether and how program-controlled interruptions (PCI) 
are to be used for control of dynamic buffer allocation and 
deallocation. For the meaning of the operands, see the discussion 
of program-controlled interruptions in Dynamic and Static Buffer 
Allocation in this chapter. 



[RESERVE= 

(integer 1, 
[integer2])] 



TERMINAL [BUFSIZE=integer] 



LOGTYPE BUFSIZE=integer 



integer 1 specifies the number of bytes to be reserved in the first 
buffer of each incoming message for inserting data by the 
DATETIME and SEQUENCE macros, data by the DATETIME 
and SEQUENCE macros, integer! optionally specifies the number 
of bytes to be reserved in all buffers, except the first, for inserting 
characters by the DATETIME macro. See the descriptions of these 
macros, and the discussion of this operand in the description of the 
Hne group DCB macro. 

Overrides the buffer size specified by the BUFSIZE= operand of 
the line group DCB macro, but only for buffers containing outgoing 
messages destined for this station. 

Specifies the size of the buffers to handle messages destined for the 
logging medium when logging of messages is specified by a LOG 
macro. 



Design Considerations 



Management of data buffers for incoming and outgoing messages is an important 
factor in running a TCAM system at optimal efficiency. There are several factors 
that a system programmer must consider in weighing the trade-off of time and 
main storage. 

L The user must specify enough buffer units to assure no loss or undue delay of 
data. 

2. The user must select the size of the buffer units and buffers to accommodate 
his message. 

3. The user must decide whether to use the program-controlled interruption (PCI) 
feature for control of dynamic buffer allocation and deallocation. 

4. The user must determine the number of buffers to be assigned initially to each 
line in a line group for sending and receiving operations, and the maximum 
number of buffers to be assigned to each line. 

The following hsts may aid the system programmer in dealing with the first two of 
these factors; the other factors are discussed in turn below. 



( 



70 OS/MFT and OS/MVT TCAM Programmer's Guide 



Size of Buffers 



Relative Advantages of Larger vs. Smaller Buffers 
Parameter A dvantages 



larger buffers 

(more units per buffer) 



1. Fewer buffers required for a message; 
consequently overhead required by 
TCAM to manipulate buffers is de- 
creased. 

2. When dynamic allocation of buffers is 
used, the possibility of losing data be- 
cause of a delayed PCI is decreased. 

3. Number of PCIs required (if PCI is 
specified) is decreased. 

4. Better use is made of the disk access 

method employed by TCAM 
(multiple-arm support) because there 
is a larger number of contiguous re- 
cords than there would otherwise be. 

5. There are fewer queuing operations 
per quantity of data; this results in a 
saving of time. 



smaller buffers 
(fewer units per buffer) 



Units in smaller buffers tend to be 
returned to the available-unit queue 
more rapidly than units in larger buf- 
fers/ (since it takes less time to empty 
and fill a smaller than a larger buffer). 
Since units in smaller buffers are 
available for reuse sooner than equiv- 
alent units in larger buffers, a smaller 
unit pool is possible when smaller 
buffers are used. 
When smaller buffers are used, 
TCAM's work load is broken into 
smaller pieces; this results in a more 
equitable allocation of processing time 
among message segments in main 
storage. 



Defining Buffers 



71 



Number of Units 



Relative Advantages of Having Many vs Few Units in the Pool 



Parameter 

more units in system 



fewer units in system 



Advantages 

1 . Likelihood of losing message data 
coming in over a line is decreased. 

2. Outgoing messages are less likely to 
be delayed as a result of waiting for a 
buffer. 

1 . Main storage is utilized more effi- 
ciently. Since the number of units in 
the free unit pool is not excessive, 
main storage is saved. 



Size of Units 



Relative Advantages of Larger and Smaller Units 



larger units 



1 . Disk space is used more efficiently, 
since there are fewer interrecord gaps. 

2. Proportion of area available for text 
to area containing management in- 
formation is relatively large. 

3. Since more data is transmitted per 
CCW on line and disk, channel activi- 
ty is relatively light; this results in a 
saving of channel fetch time and CPU 
time. 

4. Fewer channel program blocks 
(CPBs) are needed for transferring 
the same amount of data to and from 
disk; this results in a saving of storage 
space and time (since there is less 
queuing of CPBs). 



,1 



smaller units 



1. Duplicate headers (used for multiple 
routing of messages) take up little 
room. 

2. User can specify a large range of 
buffer sizes without wasting space in 
main storage and on disk. 

3. Allocation of buffers can be more 
dynamic with smaller units, since 
smaller units are passed around the 
TCAM system more rapidly than larg- 
er units. 



c 



72 OS/MFT and OS/MVT TCAM Programmer's Guide 



Dynamic and Static Buffer Allocation 

When the PCI= operand of the DCB for a Une group is coded to permit program- 
controlled interruptions, a PCI may occur during the fiUing of the first and each 
subsequent buffer assigned to a line group. When this interruption is received, 
control is given to a TCAM PCI routine. 

If PCI = A is coded, when the first interruption occurs, a number of buffers equal 
to the difference between the maximum number assigned to a line group (specified 
by the BUFMAX= operand of the DCB) and the number initially assigned to the 
line group (specified by the BUFIN= operand of the line group DCB for a 
receiving operation and by the BUFOUT= operand for a sending operation) is 
assigned as soon as possible to the line group. On subsequent PCIs, the buffer 
immediately preceding the one being filled or emptied is deallocated (for a sending 
operation, the buffer units are returned to the available-unit queue; for a receiving 
operation, the buffer is sent to the Message Handler for that line group) and a 
new buffer is requested to keep the number of buffers assigned to the line group 
equal to that specified by BUFMAX=. 

When PCI=R is coded, the previous buffer is deallocated when the second and 
subsequent PCIs occur, but no requests are made for additional buffers. If 
program-controlled interruptions are not permitted (PCI=N), or if only dealloca- 
tion is specified (PCI=R), then the number of buffers assigned initially must be 
sufficient to handle the entire transmission. 

If PCI=N is specified, no deallocation of buffers occurs until an BOB, ETB, or 
ETX control character is received; if the message contains no such characters, no 
deallocation occurs until the transmission is completed. 

If PCI=X is specified, after a buffer is filled (receive operations) or emptied (send 
operations) a PCI occurs while filUng or emptying the next buffer. The first 
buffer is not deallocated but a new one is allocated. Buffer deallocation occurs at 
the end of transmission, or when an EOB/ETB control character is sent, if 
STARTMH specifies EOB/ETB checking. 

Advantages: 

• When PCI= A is coded, fewer buffers need be assigned initially to a line since 
dynamic allocation brings the number of buffers assigned up to the value 
specified by BUFMAX= and maintains this number if possible. 

• When PCI=A is coded and a negative response to invitation occurs, only the 
number of buffers assigned initially, rather than the maximum number assigned 
to the line, have been fruitlessly allocated. 



Defining Buffers 73 



• When PCI= is specified as A or R, buffers are continuously being deallocated; 
the free-unit pool is therefore continuously being replenished and a smaller unit 
pool is required. 

• When PCI= specifies A or R, a message is moved one buffer at a time; there- 
fore, fewer CPBs are required. 

Disadvantages: 

• Dynamic allocation and deallocation of buffers takes processing time. 

• When reusable disk queues are used, records written to disk by the PCI inter- 
rupt are not serviced until the entire message is queued. If the length of time 
required to enter a message is excessive, or if reusability servicing is very 
frequent, records may be overlaid. If this occurs, TCAM will terminate abnor- 
mally with a system code of 045 and with a return code of 02 or 03 in register 
15. 

Note: In order for dynamic allocation to work properly for BSC lines, the 
BUFMAX= operand of the line group DCB macro must specify a value that 
is at least two greater than that specified by the larger of either the 
BUFIN= or the BUFOUT= operand of the line group DCB macro. 

For start-stop lines using dynamic allocation, a specification of BUFIN=2, 
BUFMAX=2 may cause inefficient dynamic allocation. 

Initial and Maximum Number of Buffers per Line 

The number of buffers that should be assigned initially to each line in the line 
group (by the BUFIN= and BUFOUT= operands of the line group DCB macro) 
depends upon the following factors: 

• terminal type; (| 

• terminal speed; 

• line speed; 

• whether dynamic allocation of buffers is specified. 

The number of buffers to be assigned initially varies directly with the speed of the 
line and the terminal; the faster the data is transmitted, the higher the initial 
assignment should be. 

The maximum number of buffers assigned to a line in the group (by the 
BUFMAX= operand of the line group DCB macro) also depends upon the Une 
and terminal speed. For a system using dynamic allocation of buffers, allowance 
should be made for the fact that program-controlled interruptions might not be 
accepted by the CPU in time for buffer replenishment to be effective for any 
particular buffer. For high-speed BSC lines, dynamic allocation may not be 
totally effective; that is, there may not be a one-to-one correspondence of re- 
placement buffers to replaced buffers. If this happens consistently, incoming data 
may be lost and bit 6 turned on in the message error record. The higher the Hne 
speed, the greater the disparity may become. When dynamic allocation is not used 
by the system, BUFMAX= is ignored. 

The buffers assigned to each line in a line group by the BUFIN= operand of the 
Une group DCB macro and the buffers assigned to each line by the BUFOUT= 
operand of the line group DCB macro are never assigned to the same line at the 
same time. The buffers specified by BUFIN= are assigned to a Une just before a 
station is invited by TCAM to enter a message; the buffers specified by 
BUFOUT= are assigned immediately before a station on the line is selected to i 

receive a message. Hence, when the user is deciding how many units to define to 



74 OS/MFT and OS/MVT TCAM Programmer's Guide 



handle initial line operations, he need consider only the larger of the values 
specified by BUFOUT= and BUFIN= for each line in a hne group, and not the 
sum of the two values. 

Other Buffer Design Considerations 

• If the buffer size (as specified by the BUFSIZE= operand of the Hne group 
DCB, TERMINAL, LOGTYPE, or PCB macro, or the BUFL= operand of the 
input or output DCB) is not a multiple of the effective unit size (as specified by 
the KEYLEN= operand of the INTRO macro), buffer space is wasted. For 
example, if the INTRO macro specifies KEYLEN=36 and the DCB macro for 
a line group specifies BUFSIZE=100, 108 bytes (that is, 36 X 3) are assigned 
to the buffer, but only 100 bytes are available for prefix and message data. 
Thus, 8 bytes are wasted for each such buffer. 

• If disk queuing is used, try to ensure that the buffer size specified by the source 
of a message is equal to the buffer size specified by the destination. The source 
of a message may be either a station or an appHcation program. If it is a 
station, that station's line group DCB macro determines the buffer size of 
messages that it may enter; if it is an appHcation program, a PCB macro deter- 
mines buffer size. The destination for a message also may be either a station or 
an application program. Buffer size for an accepting station is determined 
either by that station's Hne group DCB macro or a TERMINAL macro (if the 
buffer size is specified on the TERMINAL macro, this value overrides the value 
specified on the Hne group DCB). A PCB macro determines buffer size for an 
appHcation program that is the destination for a message. When the buffer 
sizes specified for the origin and the destination of a message are different, data 
movement occurs because of the necessity of adding or deleting prefixes when 
the message is placed in the buffers for the destination. (The message is 
queued on disk with its old prefixes; when it is removed from a queue and 
placed in buffers of a different size, prefixes must be added or removed and 
message data must consequently be shifted.) Movement of data takes time. 
Figure 5 illustrates a situation in which 706 bytes of a 1076-byte message must 
be moved because of a difference in origin and destination buffer size. 

• TCAM does not consider a message that has been sent to an appHcation 
program to be ^'serviced" until the succeeding GET is completed; therefore, 
buffers are not released until the succeeding GET is completed and extra 
buffers must be aHocated to compensate for those not released yet. 

Buffering and queuing are closely related concepts; the discussions of main- 
storage and disk queuing in the chapter Defining Data Sets should be read in 
conjunction with the present chapter. 



Defining Buffers 75 



30 bytes 



"V" 



23 bytes 



70 bytes 



DATA 



DATA 



DATA 



77 bytes 



30 bytes 



HEADER 
PREFIX 


DATA 



>^ 



">^ 



r 



No Data Movement 
for these Units 



Data Movement: 




Relevant Macro Operands 



MACRO 


OPERAND 


INTRO 


KEYLEN=100 


Line Group DCB 
for Incoming Line 


BUFSIZE=400 


Line Group DCB 
for Outgoing Line 


BUFSIZE=1200, 
BUFOUT=l 



70 bytes 
A 



HEADER 
PREFIX 


DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



DATA 



message length=1076 bytes. 



r 




V 






46_bytes___ 


6 bytes 






DATA 


EMPTY 






















DATA 


EMPTY 



Figure 5. 706-Byte Data Movement Resulting from Size Disparity between Input and Output Buffers 



i 



16 OS/MFT and OS/MVT TCAM Programmer's Guide 



Defining the MCP Data Sets 



The Message Control Program may refer to four types of data sets. Two are 
required for every MCP: 

• The Une group data set and 

• The message queues data set. 

The two optional data sets are: 

• The checkpoint data set, if the checkpoint facility is desired; 

• The log data set, if the logging function is desired. 

Log data sets are not TCAM data sets; they are discussed briefly below. Other 
data sets are needed if there are any application programs; these data sets are 
described in the chapter dealing with TCAM support for application programs. 

With one exception (a message queues data set in main storage with no disk 
backup), TCAM data sets are defined by DCB macro instructions. The total 
number of TCAM MCP data sets may not exceed 255. 



Line Group Data Sets 



A line group data set consists of the lines in a line group over which messages are 
transmitted to and from the central processing unit. The user must specify one 
line group DCB macro instruction for each line group in the system. 

Characteristics of a Line Group 

A line group may consist of from one to 255 lines. (The size of a Une group is also 
limited by the fact that the INVLIST= operand of the line group DCB macro can 
be no longer than 255 characters, including commas; thus, if each of 255 lines has 
an invitation list associated with it, the Unes cannot all be accommodated within 
the same Une group.) AU Unes in the group must have the following common 
characteristics: 

Either aU Unes in the group are switched or aU are nonswitched. 
Either all lines in the group use start-stop transmission or all use binary syn- 
chronous transmission. 

AU Unes are associated with stations having the same device characteristics. 
AU lines are preassigned the same number of buffers to handle the initial 
segments of incoming messages. 
All Unes use the same invitation delay. 
AU lines use the same Message Handler. 
No line in the group is a member of another group. 

AU lines in the group are associated with the same type of transmission control 
unit. 

Creating a Line Group Data Set 

A Une group data set is defined by a Une group DCB macro instruction, which 
creates a data control block for the line group. Parameters based on the keyword 
operands specified in the macro are included in the data control block. 

Operands of the line group DCB macro enable one to specify functions concerned 
with buffering (BUFOUT, BUFIN, BUFSIZE, BUFMAX, PCI), polling (INTVL, 
CPRI, INVLIST), and message translation (TRANS) on a line-group basis. These 
operands are described in detaU in the next section. Various aspects of polling 
and translation are discussed in the chapter Defining Terminal and Line 
Control Areas , whUe the chapter Defining Buffers includes a discussion of how 
to code the DCB operands concerned with buffering. 



Defining the MCP Data Sets 77 



^ 



< 



linedcb 



keyword operands 



Line Group DCB Macro 



The line group DCB macro 

• defines a line group data set; 

• must be issued for each line group in the TCAM system; 

• identifies the Message Handler for the lines in this line group; 

• identifies the invitation Usts assigned to the lines in this group; 

• specifies the invitation delay; 

• indicates transmission priority for stations on Unes in this group; 

• specifies the number of buffers assigned initially to Unes in this group for 
sending and receiving operations; 

• specifies when buffers servicing Unes in this group are to be allocated and 
deaUocated; 

• specifies the buffer size for buffers servicing lines in this group; 

• specifies the maximum number of buffers assigned to a line at one time; 

• specifies the number of bytes to be reserved for insertion of certain data into 
buffers; 

• specifies the translation tables to be used for incoming and outgoing messages. 

The line group DCB macro defines a data control block for a line group data set. 
Parameters based on the keyword operands specified in the macro are included in 
the data control block. One line group DCB macro must be issued for each Une 
group in the TCAM system. The macro generates no executable code. 

The Une group DCB macro has the following format: 



Name 


Operation 


Operands 


linedcb 


DCB 


keyword operands 



Function: Specifies the name for the macro instruction and also for the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Are the operands that can be specified. They are described below. 
Notes: The operands may be specified in any order and are separated by commas 
with no intervening blanks. When a parameter can be provided by an alternate 
source, a symbol appears in the Alternate Source description for the operand 
associated with that parameter. When there is not an alternate source (that is, the 
parameter must be specified by the operand), the alternate source descriptor 
states None . The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be provided at execution time by the 

data definition (DD) card for the data set. If a value is provided 
by a DD statement, the macro operand must be either omitted or 



Defining the MCP Data Sets 79 



OE 



coded with a zero value (if the operand is omitted, a zero value is 
supplied by TC AM). 

The value of the operand can be provided by the problem program 
any time up to and including the data control block exit at open 
time. 



PP 



The value of the operand can be provided by the user's problem 
program any time before the data control block exit at open time. 



DSORG=TX 



MACRF=(G,P) 



If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. For information on providing parameters by DD, see the section DD 
Statements for a Line Group , For information on providing parameters by OE 
or PP, see Modifying the Data Control Block in the OS Data Management 
Services publication. 

The formats of macro illustrations, the symbols used in them, and rules for the 
interpretation of operand descriptions are all provided in Appendix A . 



Alternate Source: None. 

Function: Identifies the data set organization as that for a line group. 

Default: None. This operand is required. 

Format: DSORG=TX 



Alternate Source: None. 

Function: Specifies that access to the line group is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



INTVL= ( integer) 
\0 / 



Alternate Source: PP, OE, DD. 

Function: Specifies the numer of seconds of intentional delay between passes 
through an invitation list). 
Default: INTVL=0 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: After all the stations in an invitation list for a given Une have been invited 
to enter a message, a delay, equal to the number of seconds specified in this 
operand, occurs before invitation is restarted at the beginning of the Ust. Invita- 
tion delay is discussed in Transmission Priority in the chapter Defining Terminal 
and Line Control Areas. For switched lines, INT VL=0 should be specified. 

If tone generation is required for World Trade terminals, INTVL= 1 should be 
coded. 



< 



80 OS/MFT and OS/MVT TCAM Programmer's Guide 



CPRI= 




Alternate Source: PP, OE, DD. 

Function: Specifies the relative transmission priority assigned to the lines in this 

line group. 

Default: None. This operand is required. 

Format: R, E, or S. 

Notes: R specifies that CPU receiving has priority over CPU sending. E specifies 

that receiving and sending have equal priority. S specifies that sending has 

priority over receiving. See Transmission Priority in the chapter Defining 

Terminal and Line Control Areas for a discussion of the effect of transmission 

priority on sending messages. 



DDNAIVlE=ddname 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



EXLST=address 



Alternate Source: PP. 

Function : Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This list must be provided if data control block or user ABEND exits are 

required, and must start on a fuUword boundary. The format and contents of the 

list, and Unkage conventions to be followed when using it, are shown in the OS 

Data Management Services pubUcation. User ABEND exits are described in the 

last section of this chapter. The DCB exit is also described in Data Management 

Services . 



BUFIN= 



( integer) 



Alternate Source: PP, OE, DD. 

Function: Specifies the number of buffers assigned initially for receiving opera- 
tions for each line in the line group. 

Default: BUFIN= 1. This default is supplied at open time, rather than at assem- 
bly time. 

Format: Unframed nonzero decimal integer. 
Maximum: 15 

Notes: These buffers are assigned just before a station is permitted to enter a 
message. BUFIN=, BUFOUT=, and BUFMAX= must all be specified from the 
same source. For more information on initial assignments of buffers, see the 
chapter Defining Buffers . 



\ 



Defining the MCP Data Sets 8 1 



BUFOUT=J integer | 

V- / 



Alternate Source: PP, OE, DD. 

Function: Specifies the number of buffers assigned initially for sending opera- 
tions on each line in the line group. 

Default: BUFOUT=2. This default is supplied at open time, rather than at 
assembly time. 

Format: An unf ramed decimal integer greater than 1 . 
Maximum: 15 

Notes: BUFIN=, BUFOUT=, and BUFMAX= must all be specified from the 
same source. 



BUFMAX=J integer I 



BUFSIZE=integer 



Alternate Source: PP, OE, DD. 

Function: Specifies the maximum number of buffers used for data transfer. 

Alternate Source: PP, OE, DD. 

Function: Specifies the maximum number of buffers used for data transfer for 

each Une in this line group. 

Default: BUFMAX=2. This default is supplied at open time, rather than at 

assembly time. 

Format: Unf ramed decimal integer greater than 1 . 

Maximum: 15 

Notes: Must be no less than the larger of the numbers specified by BUFIN= and 

BUFOUT=. BUFIN=, BUFOUT=, and BUFMAX= must all be specified from 

the same source. 



Alternate Sourve: PP, OE, DD. 

Function: Specifies the buffer size in bytes used for all lines in this Une group. 

Default: None. Specification optional. 

Format: Unf ramed decimal integer greater than 35. 

Maximum: 65535 

Notes: The size specified here may be overridden on a station basis for outgoing 

messages by the BUFSIZE= operand of the TERMINAL macro. If the buffer 

size is not an even multiple of the buffer unit size specified by the KEYLEN= 

operand of the INTRO macro, storage space is wasted. The maximum number of 

units per buffer is 255. 



,4 



INVLIST=(listname 



■•jii"iii' 



Alternate Source: None. 

Function: Specifies the names of the invitation lists for the lines in the line group. 

Default: None. This operand is required. 

Format: Each listname is the name specified for the INVLIST macro defining 

the Ust for that line. Listnames are specified according to the ascending relative 

Une numbers of the lines in the group. The maximum total length of the data 

coded for this operand is 255 bytes. A and B are coded as shown. 

Notes: For information on relative line numbers, see DD Statements for a 

Line Group in this chapter. 



( 



82 OS/MFT and OS/MVT TCAM Programmer's Guide 



IVIH=mhnaine 




There must be one invitation list name for each Une in the line group. If a line is 
used for output only, a dummy invitation list name with no entries is specified. 
Any number of output-only lines may refer to the same name. No list other than a 
dummy invitation Ust may be named by more than one line. For information on 
invitation lists, see the Invitation section in Defining Terminal and Line 
Control Areas. 

The two sets of A/B suboperands are meaningful only for lines attached to a 
channel through an IBM 2701 Transmission Control Unit, in which case: 

The first A specifies that communications are to be through the 2701 Data 
Adapter Unit's Dual Communication Interface A. 

The first B specifies that communications are to be through the 270 1's Dual 
Communication Interface B. This parameter is not coded if this feature is not 
present on the 2701. 

The second A specifies that transmission will be in Code A for the 2701 Data 
Adapter Unit Dual Code Feature. 

The second B specifies that transmission will be in Code B for the 2701 Dual 
Code Feature. This parameter is not coded if this feature is not present on the 
2701. 

A is the default value for both sets of suboperands. 

If either or both of the A/B suboperands are omitted, the commas that precede 
them must still be coded. For example, if the names of the invitation lists for the 
lines in this line group are LISTl, LIST2, and LIST3, and if the A/B suboperands 
are to be omitted from this operand, the operand might be coded as follows: 

,INVLIST=( LISTl 



Alternate source: None. 

Function: Specifies the name of the Message Handler for the line group repre- 
sented by this DCB macro. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols, and must be 
the same as the name specified in the name field of a STARTMH macro. 



Alternate Source: PP, OE, DD. 

Function: Specifies if and how a program-controlled interruption (PCI) is to be 
used for control of buffer allocation and deallocation. 
Default: (PCI=A, A). This default is supplied at open time, rather than at 
assembly time. 

Format: Framing parentheses required. N, R, X, and A coded as shown. 
Notes: The suboperands apply to receiving and sending operations, respectively. 
N specifies that no PCIs are taken during filling (on receive operations) or empty- 
ing (on send operations) of buffers. Once data in a buffer has undergone BOB 



Defining the MCP Data Sets 83 



checking, the buffer is deallocated (except that the current buffer is not deallocat- 
ed if there is room in it for a portion of the next block). 

R specifies that after the first buffer is filled (on receive operations) or emptied 
(on send operations), a PCI occurs during the filling or emptying of each succeed- 
ing buffer. The finished buffer is deallocated, but no new buffer is allocated to 
take its place. 

X specifies that after a buffer is filled (on receive operations) or emptied (on send 
operations), a PCI occurs during the filling or emptying of the next buffer. The 
first buffer is not deallocated, but a new buffer is allocated. Buffer deallocation 
occurs at the end of transmission, or when an EOB/ETB control character is sent, 
if EOB/ETB checking is specified in the STARTMH macro. 

PCI=X (or N) must be used if the TCAM network defines logical messages, and 
if the SETEOM macro specifies PROCESS= YES, to ensure that logical messages 
are not deblocked until block checking is performed; otherwise, a logical message 
containing an error could be routed to its destination. Logical messages are 
discussed in Handling Logical Messages in the chapter Designing the Message 
Handler . The SETEOM macro is discussed in Functional Macro Instructions . 

A specifies that after the first buffer is filled (on receive operations) or emptied 
(on send operations), a PCI occurs during the filling or emptying of the next 
buffer. The first buffer is deallocated, and another buffer is allocated in place of 
it. The program-controlled interruption is more thoroughly described in the 
chapter Defining Buffers . 

RESERVE= ( UntegerlM,i integer! H j \| 

Alternate Source: PP, OE, DD. 

Function: integer 1 specifies the number of bytes reserved in the first unit of a 
buffer receiving the first incoming segment of each message entered on a Hne in 
this line group. The reserved bytes are for insertion of characters by the 
DATETIME and SEQUENCE macros, integer I may be specified as one less 
than the required number of reserved bytes if LC=OUT is specified on the 
STARTMH macro and the terminal in use has EOA Hne-control characters. 
(TCAM's use of LC=OUT results in the conversion of EOA Une-control charac- 
ters to reserve characters which, in effect, gives the user one more reserve charac- 
ter than is specified on the line group DCB macro.) integer! specifies the number 
of bytes reserved in the first unit of all buffers, except the first, for insertion of 
characters by the DATETIME macro. 
Default: RESERVE=(0,0) 
Format: Unframed decimal integers. 
Maximum: For each, 255. 

Notes: integer! is relevant only in a multiple-buffer header situation when 
DATETIME is to insert data in a portion of the header that is not in the first 
buffer (see the description of DATETIME for an example of executing 
DATETIME on a portion of the header not located in the first segment). 

Data may be inserted in either an incoming or an outgoing message header, but 
space must be reserved in the incoming header. On the outgoing side, reserved 
space is retained for the first buffer only; thus, a DATETIME or SEQUENCE 
macro, if specified in an outheader subgroup, must operate on the first segment of 



( 



84 OS/MFT and OS/MVT TCAM Programmer's Guide 



TRANS= table 



the message. No space need be reserved for data inserted by means of a 
MSGEDIT macro. 

The Scan Pointer section of the chapter Designing a Message Handler de- 
scribes how TCAM handles reserve bytes. 

Each integer must be at least three less than the value specified in the KEYLEN= 
operand of the INTRO macro, minus the header or text prefix size Each buffer 
containing header data should be large enough to accommodate the segment itself 
plus any data that may be inserted by DATETIME and SEQUENCE macros. If a 
buffer containing header data does not have a sufficient number of bytes reserved 
in it to accommodate data inserted by a DATETIME or SEQUENCE macro, the 
macro does not execute, and control is passed to the next instruction in the MH. 
Unused reserve bytes are removed from an outgoing message segment when it is 
sent to its destination. 



Alternate Source: PP, OE. 

Function: Specifies the translation table for this line group. 

Default: TRANS=EBCD. This default is supplied at open time rather than at 

assembly time. 

Format: Either the name of a user-defined table conforming to the rules for 

assembler language symbols, or one of the following four-byte symbols: 

1030 1030 transmission code 

1050 1050 transmission code 

105F Folded 1050 transmission code 

1060 1060 transmission code 

2260 2260 remote transmission code 

2265 2265 transmission code 

2740 2740 transmission code 

274F Folded 2740 transmission code 

BC41 2741 BCD code 

EB41 2741 EBCDIC code 

CR41 2741 correspondence code 

ITA2 World Trade terminals transmission code 

ZSC3 World Trade terminals transmission code 

TTYA 83B3, 1 15A transmission code 

TT YB 33/35 parity transmission code 

TTYC 33/35 non-parity transmission code 

6BIT 2780 6-bit transmission code 

ASCI 2780, 3270, 3670, 3735, 360 CPUs, Model 20 ASCII tranmission 

code 

EBCD 2770, 2790, 3270, 3670, 3780, 1 130, 2260 Local, 2780, 360 CPUs, 

Model 20 EBCDIC transmission code. 

Notes: Specification of a user-defined table is described in Message Translation 
in the chapter Designing the Message Handler 

Translation is from transmission code to EBCDIC for incoming messages and 
from EBCDIC to transmission code for outgoing messages. For incoming transla- 
tion to occur, a CODE macro must be executed in the incoming group handling 
the message. For outgoing translation to occur, CODE must be executed in the 
outgoing group handling the message. If this operand is omitted, no translation is 



Defining the -MCP Data Sets 85 



SCT=table 



performed. TRANS = ASCI must be specified for US ASCII 3270 terminals 
whether or not data is to be translated. 

The table specified for translation can be changed for messages from a particular 
line or station by the CODE macro and by the use of path switches. 
TRANS=EBCD should be coded for lines to stations using EBCDIC line code, if 
any of the stations may enter operator commands (TCAM uses the CODE macro 
to check for operator commands). 

For more information on the symbols, and on translation in the TCAM system, 
see Message Translation and the description of the CODE macro in the chapter 
Designing a Message Handler. 



Alternate Source: None. 

Function: Specifies the name of the special characters table (SCT) used for this 

Hne group. 

Default: The table specified for the TRANS= operand is assumed for the SCT= 

operand if this operand is omitted. 

Format: One of the four-byte codes permissible for the TRANS= operand. 

Notes: If a user-specified table is coded for the TRANS= operand, the SCT= 

operand must be coded. The SCT is an internal TCAM table containing certain 

device-specific, line-control characters needed by TCAM whether or not Une- 

control characters are left in incoming messages. TCAM makes no provision for 

the user to specify his own special characters table. The contents and layout of 

the SCT are described in the TCAM PLM . 



A 



DD Statements for a Line Group i 

At least one DD statement must be issued for each line group data set. Either of 
two schemes may be followed in issuing DD statements for Une groups. 

1 . If at system generation time a UNITNAME macro is issued to specify the lines 
in a Une group and to assign to them a single name, then a single DD statement 
may be issued for this line group at MCP execution time. This DD statement 
would have the format 

//ddname DD UNIT=( name,n ) 

where ddname is the name specified by the DDNAME = operand of the DCB 
macro for the line group, name is the name assigned to this group of lines by 
the NAME= operand of the UNITNAME macro, and n is the number of lines 
to be allocated from among the lines whose hardware addresses are coded in 
the UNIT= operand of UNITNAME. 

Example: 

At system generation time, the following UNITNAME macro was issued to 
define a group of lines: 

UNITNAME UNIT=( 021 ,022,024,025 ) 
NAME-GROUPONE 

(The four numbers in the UNIT= operand are the hardware addresses of four 
lines, and are assigned to the lines by lODEVICE macros at system generation 
time.) At execution time for the Message Control Program, the following DD 
statement might be issued for this line group: 



86 OS/MFT and OS/MVT TCAM Programmer's Guide 



( 



I 



//ddname DD UNIT=( GROUPONE, 4 ) 

In this case, the Une group data set would consist of the four Hnes defined by 
the UNITNAME macro. Relative line numbers are assigned to the lines in the 
same order as they appear in the UNIT= operand of the UNITNAME macro. 
If the UNIT parameter of the DD statement were coded 

UNIT=(GROUPONE,2), the line group data set would consist of only the first 
two lines specified in the UNIT= operand of the UNITNAME macro. 
2. A DD statement may be issued for each Une in a line group; these DD state- 
ments are concatenated as follows (assume that the Une group consists of three 
lines): 

//ddname DD UNIT=address 
// DD UNIT=address 
// DD UNIT=address 

where ddname is the name specified by the DDNAME= operand of the DCB 
macro for the Une group, and address is the hardware address of the Une, as 
assigned at system generation time by an lODEVICE macro. Note that DD 
statements for aU lines in a line group are Usted under a single ddname . When 
this scheme is used, the order in which the DD statements for a Une group are 
arranged determines the relative Une numbers specified in TERMINAL macros; 
that is, the first Une specified is relative line number one, the second Une 
specified is relative line number two, etc. (see the discussion of the TERMI- 
NAL macro in the chapter Defining Terminal and Line Control Areas . 

Note: The type of stations on lines in the line group for which the DD 
statement is issued must be the same as the type specified by the lODEVICE 
macro that defines the line at system generation time. Be sure that the line 
you specify in the UNIT= parameter of your DD statement can handle the 
stations assigned to that line by TERMINAL macros. Otherwise, the data 
set will not open. 

Certain of the line group DCB macro operands may be omitted from the DCB 
macro and be specified at MCP program execution time by coding them as 
subparameters in the DCB parameter of the first DD statement for a Une group. 
The way in which the DCB parameter would be coded to specify any one of these 
DCB macro operands is: 

DCB=( BUFIN=integer , BUFOUT=integer , BUFMAX=integer ) 
DCB=( INTVL=integer ) 

DCB=(CPRI=^E> ) 

DCB=( RESERVE=( integer [ , integer] ) ) 
DCB=(PCI = (( N I , ^ N, 

DCB=( BUFSIZE=integer ) 

These subparameters are described in the discussion of the Une group DCB macro. 
More than one DCB operand may be specified in this manner. Note that the 
BUFIN=, BUFOUT=, and BUFMAX= values must be specified from the same 
source. 

If the above DCB operands are stiU zero after OPEN, the following defaults are 
used: 



Defining the MCP Data Sets 87 



//ddname 


DD 


// 


DD 


// 


DD 



BUFIN=1 

BUF0UT=2 

BUFMAX=2 ( 

CPRI=S 

RESERVE=0 

PCI=(N,N) 

BUFSIZE=value of KEYLEN= on INTRO 

Example: 

The following DD statements define a line group consisting of three lines. The 
PCI= operand was not specified in the line group DCB macro, but is being 
specified at program execution time on the DD statement. 

UNIT=024,DCB=( PCI=(R,R) ) 

UNIT=022 

UNIT=025 

In this example, the line whose address is 024 is assigned relative line number 1, 
the line whose address is 022 is assigned relative Une number 2, and the Une whose 
address is 025 is assigned relative line number 3. 

Message Queues Data Sets 

In a TCAM system, messages entered by remote stations are queued by destina- 
tion. A destination may be a station on a Une or an appHcation program. Because 
each incoming message is placed on a queue for its destination rather than being 
sent to the destination immediately, overlap of line usage in I/O operations is 
possible. Messages having a common destination may be received simultaneously 
from more than one source; the destination itself may also be entering or accept- 
ing a message. 4 

Destination queues for each destination (Une, terminal, or appUcation program) 
and a queue for each logging medium used (for message logging) are located in 
one or more message queues data sets, which may reside either in main storage or 
on a direct-access storage device. Messages may be queued 

• on reusable disk; 

• on nonreusable disk; 

• in main storage only; 

• in main storage with backup on reusable disk; 

• in main storage with backup on nonreusable disk. 

Although there are five queuing techniques, no more than three message queues 
data sets ever need to be defined; one on reusable disk, one on nonreusable disk, 
and one in main storage. 

In the foUowing discussion we shaU first explain each of the five message queuing 
techniques, giving their relative advantages and disadvantages, and then describe 
how each may be implemented. 

Messages may be queued by destination Une or by destination terminal; this topic 
is discussed in the Message Priority and Queuing section of the Defining 
Terminal and Line Control Areas chapter. 



Disk Queuing 



^^ OS/MFT and OS/MVT TCAM Programmer's Guide 



TCAM supports secondary-storage message queuing on the IBM 23 11 Disk 

Storage Drive, the IBM 2314 Direct Access Storage Facility, and the IBM 3330 i 

Disk Drive ^ 



The objective of TCAM's secondary-storage queuing scheme is to optimize 
channel and disk performance. Rotational delay time is minimized by using 
sequential disk records wherever possible. The user may specify more than one 
DASD volume for a data set; if he does, TCAM assigns relative record addresses 
across volumes, so that the next relative record address after that of the last 
record on a track is on another volume. Figure 6 illustrates this relative-record 
addressing scheme, which facilitates efficient multiple-arm support. TCAM's 
multiple-arm support (described below) permits overlap of seek time on multiple 
volumes and overlap of channel operations on multiple channels. Seek time is 
further optimized by minimizing disk arm movement. 

Advantages and Disadvantages of Disk Queuing 

Locating destination queues in a message queues data set residing on a disk rather 
than in a data set residing in main storage with no disk backup results in certain 
advantages: 

1. Locating queues on disk rather than in main storage results in more main 
storage being available to the user. 

2. With disk queuing, messages being sent to a station that temporarily inoperative 
may be intercepted by a HOLD macro issued in the Message Handler, and sent 
out at a later time. The interception facility is not available for destinations 
whose queues are located in a main-storage data set having no disk backup. 

3. By issuing a POINT macro in conjunction with a GET or READ macro in an 
application program, the user may retrieve from its destination queue the 
original copy of a message that has already been successfully transmitted to a 
destination station or sent to an application program. This retrieval capabihty 
(discussed in the Message Retrieval section of the chapter Writing TCAM- 
Compatible Application Programs) mighi be used to permit a message that was 
successfully sent to a terminal but lost at the terminal (due, perhaps, to a tape 
breakage) to be retransmitted. Messages cannot be retrieved from main- 
storage queues. 

4. When disk queuing is used, it is possible to take advantage of the TCAM 
checkpoint/restart facility, which is described in the chapter Using TCAM 
Service Facilities . Main-storage queues cannot be checkpointed; unless disk 
backup is provided, the data in such queues is lost when the TCAM system 
closesdown or fails. 

Locating message queues in a data set on disk rather than in a main-storage data 
set also has certain disadvantages: 

L Disk queuing is slower than main-storage queuing; that is, a message that is 
queued on disk takes longer to reach its destination than a message that is 
queued in main storage, all other things being equal. 

2. Disk queuing ties up disk space and disk channels that otherwise could be used 
by other jobs (for example, by a batch-processing job) in a computing system 
not dedicated to TCAM. 

Main-storage queuing with disk backup (discussed below) preserves most of the 
advantages of disk queuing while achieving a faster response time than disk 
queuing alone. To obtain main-storage queuing with disk backup, the user must 
define at least two message queues data sets — one residing in main storage, the 
other on reusable or nonreusable disk. 

Specifying Channel Program Blocks 

Channel program blocks (CPBs) are used to transfer data between buffers and 
direct-access secondary-storage devices. A CPB consists of 72 bytes of control 
information plus a work area the size of one buffer unit. One CPB is involved 
whenever the contents of a buffer unit are written on disk or read from disk. 



Defining the MCP Data Sets 89 



Volume 1 



Volume 2 



Volume 3 







Cylinder 



Track 




1 
2 
3 

4 
5 

6 
7 
8 
9 

1 



Relative 
Record Numbers 



12 3 

12 13 14 15 

24 27 

36 39 

48 51 

60 63 

72 75 

84 87 

96 99 

108 111 

120 123 

132... 



Relative 
Record Numbers 



4 5 6 7 

16 17 18 19 

28 31 

40 43 

52 55 

64 67 

76 79 

88 91 

100 103 

112 115 

124 127 



Relative 
Record Numbers 



8 9 10 11 

20 21 22 23 

32 35 

44 47 

5(> 59 

68 71 

80 83 

92 95 

104 107 

116 119 

128 131 



Figure 6. Relative Record Numbers of Disk Message Queues Data Set Assigned Across Three Volumes 

CPBs that are not being used currently are queued in a free pool . When a CPB is 
to be used in writing data onto disk, TCAM "swaps" the CPB with a full buffer 
unit (the contents of which are to be written onto the disk); that is, the CPB work 
area is assigned to the available-unit queue, and a full buffer unit is assigned to the 
CPB to replace the work area. This swapping of units is accompUshed by chang- 
ing addresses internally; no movement of data occurs. 

When the CPB has been used in reading from disk, its full work area is swapped 
with an empty unit; that is, the CPB work area is assigned to the outgoing group 
of the Message Handler for the destination and is replaced by a unit from the 
available-unit queue. Thus, the unit pool always has the same number of units, 
even though they are not necessarily the same units that were originally in the 
pool. The number of work areas assigned to the CPB is also constant, although 
some of the work areas were once buffer units. This swapping feature saves time, 
because data need not be moved from the CPB unit into the buffer unit. 

Note: Swapping does not occur for units involved in a data transfer result - 
ing from disparity in size between origin buffers and destination buffers (for 
a discussion of such data transfer, see Other Buffer Design Considerations in 
the Designing Buffers chapter). In this case, data is moved from the CPB 
unit to an empty unit. 



i 



90 OS/MFT and OS/MVT TCAM Programmer's Guide 



The number of CPBs in a TCAM system is specified by the CPB= operand of the 
INTRO macro. The number that should be specified must be determined experi- 
mentally and depends upon the message traffic during the peak period of activity 
in the TCAM system. The following formula may be used to determine initially 
how many CPBs to specify in a system: 

(2(BU)-H)m +r 
60 

where r is 1 if reusable disk and otherwise, m is the average number of mes- 
sages transmitted per minute during peak periods of activity, B is the number of 
buffers per message, and U is the number of units per buffer. The maximum 
number of CPBs that TCAM can use at any one time can be determined by 
adding the number of units per buffer for every destination QCB in the system 
(destination QCBs are generated when TERMINAL and TPROCESS macro 
instructions define stations and application programs to which messages may be 
directed). There is not much likelihood that TCAM will need this maximum 
number of CPBs. 

Although the minimum CPBs that may be specified is one, it is strongly recom- 
mended that the number of CPBs specified be equal to the maximum number of 
buffer units per buffer in the system, so that an entire buffer can be dispatched 
with a minimum number of operations. Specification of too few CPBs results in 
poor disk performance; messages are delayed while TCAM waits for CPBs to 
become available. Specification of too many CPBs results in waste of main 
storage; each CPB is 72 bytes plus the length of a buffer unit. 

How to determine if too many CPBs were specified on the CPB=: operand of the 
INTRO macro instruction: 

The type of queuing used by the CPB free pool is LIFO (last-in first-out), so that 
any unused CPBs at the bottom of the queue remain in the state they were in at 
TCAM initialization time (all zeros). 

The lEDFCPB field of the AVT points to the first entry in the CPB free pool; the 
thirteenth word of each CPB points to the next lower CPB entry on the queue. 
Consequently, a dump can be taken before the MCP is closed down, and by 
tracing the CPBs until one is found in the dump whose first few words are zeros, 
the user can determine if too many CPBs were specified. For instance, if 50 
CPBs were specified, and the first several words of CPB number 22 in the chain 
contained all zeros, then 29 of the 50 CPBs were not used. If the next execution 
of this same TCAM MCP incorporates the same technique of buffer allocation 
and is likely to be under the same Une and traffic conditions, specifying 25 CPBs 
should be adequate. 

How to Determine if too few CPBs were specified on the CPB= operand of the 
INTRO macro instruction: 

If, as a result of tracing CPBs in the dump discussed above, no CPBs are found 
whose first few words are zeros, one of two conclusions can be drawn: 

1. The exact number of CPBs required to avoid poor disk performance was 
specified(that is, all the CPBs were being used simultaneously on at least one 
occasion during the execution of this MCP, so that there was no delay in 
message traffic to or from disk). 

2. More likely, not enough CPBs were specified so that on one or more occasions. 



Defining the MCP Data Sets 9 1 



TCAM had to wait until a CPB was available before it could place a message 
on (or remove it from) disk. 

The user should increase the number of CPBs the next time he executes this 
TCAM MCP under the same line and traffic conditions, unless he is changing 
from static to dynamic buffer allocation (if buffer allocation is static, there should 
be enough CPBs specified to handle a message). He can then determine, by the 
technique described in the previous section, whether the increased number of 
CPBs is too many (or, if the CPB at the bottom of the CPB free pool still does not 
contain all zeros, then specify an even larger number of CPBs the next time this 
MCP executes). 

Preformatting DASD Message Queues Data Sets 

Before the Message Control Program is started, TCAM expects message queues 
data sets on both reusable and nonreusable disk to be totally preformatted by the 
lEDQXA utility described in the chapter System Preparation . The records, into 
which each disk queue is segmented, should have the same length as that specified 
by the KEYLEN= operand of the INTRO macro. The name of the disk message 
queues data set is originally specified on the lEDQDATA DD statement for the 
lEDQXA program. The data set may be cataloged when the lEDQXA job is run. 

Message queues data sets located on disk should be preformatted before each cold 
restart of the MCP. 



Using Multiple-Arm Support 



Disk efficiency can be increased by spreading the disk message queues data set 
over several volumes (up to 16 volumes per disk data set). At initialization time, 
this is indicated by listing several volumes on the lEDQDATA DD card for the 
lEDQXA utihty. Each volume so indicated is initialized to contain one contiguous f 

extent of the data set. Each volume also contains identical amounts of record i 

space for the disk message queues. 

At TCAM open time, the old disk message queues data set is recognized as 
existing on several volumes. OPEN builds an input/output block (lOB) for each 
extent, permitting TCAM to issue several EXCP instructions, one per 
input/output block or extent. When the I/O Supervisor has several EXCP 
instructions to act upon, disk performance is improved by overlapping seek times 
on the various devices; that is, one drive can be seeking a cylinder while another 
drive is actively transferring data. Even better performance can be obtained by 
having the various volumes mounted on drives supported by different channels. 
This permits simultaneous search/read- write activity on more than one volume. 

Records are not assigned sequentially from beginning to end of the data set 

(although it was initially created sequentially). The record assignment algorithm 

uses the records of the first track, first cylinder, first extent, in a sequential 

manner. At the end of that track, instead of progressing to the next track of that 

same cylinder, records are assigned from the first track, first cylinder, of the 

second volume. Only one track of each volume is used before going to a new 

track on the next volume. This permits I/O requests to be made from more than 

just one volume, thus gaining the advantages of multiple EXCPs on several 

channels. The algorithm continues assigning the first track to new volumes until all 

volumes have used one track. Record assignment returns to the first volume, 

second track, first cylinder. Again, a new volume is used each time the end of a 

track is reached. This cycle repeats until the first cyUnder of all volumes is ^ 

assigned. Then the second cylinder is similarly assigned and so on until the entire i 

data set is filled. 



92 OS/MFT and OS/MVT TCAM Programmer's Guide 



This procedure is used for both reusable and nonreusable disk message queues. 

When reusable disk queuing is used, multiple-arm support increases the likelihood 
that one arm will be reading while another is writing, thus improving the efficiency 
of the system. However, this advantage may be offset by the need to construct an 
extra lOB and DEB extent for each volume, thereby increasing the amount of 
main storage required for the TCAM program. 



Reusable Disk Queues 



A reusable message queues data set can often handle the same amount of message 
traffic as a nonreusable message queues data set while occupying less disk space. 
A message queues data set located on reusable disk never runs out of disk space 
under normal conditions, and the TCAM system need never be closed down to 
replenish disk space for such a data set. In addition, when reusable disk queuing is 
used, messages for an inoperative terminal need not be trapped in the data set 
until the terminal is fixed, but may be sent to an alternate destination (specified by 
the ALTDEST= operand of a TERMINAL macro), which might be another 
terminal in close physical proximity to the first. This capabihty of automatically 
sending a message to an alternate destination is available only to the user of 
reusable disk queuing. A similar capabihty is provided by specifying a cascade Hst 
as a destination (see the description of the cascade Hst in Constructing the 
Terminal Table in the chapter Defining Terminal and Line Control Areas ). 

A reusable data set requires periodic reorganization. TCAM's method of reor- 
ganizing the reusable data set is illustrated in Figure 7. 

The data set as a whole (whether on one volume or 16) is divided into four equal 
zones (shown in Figure 7 as Zones A, B, C, and D). Messages are read into the 
four zones sequentially. By the time Zone D is full. Zone A has been prepared for 
reuse, and a cycle of use and reuse of the data set has been initiated. 

Figure 7 shows a 'ioadpoint" located half-way through each zone. Assume that 
the data set has been in use for some time; Zones A and B contain messages 
received relatively recently. When the loadpoint for Zone C is reached, a TCAM 
reorganization routine is automatically activated. This routine checks Zone A for 
messages that have not yet been sent or canceled. Such messages are placed on 



I 



Loadpoint 




Send to alternate destination 



dummy" canceled messages 



Figure 7. Reorganizing a Reusable Data Set 



Defining the MCP Data Sets 93 



the queue for the alternate destination specified by the ALTDEST= operand of 
the TERMINAL or TPROCESS macro for the original destination or on the 
queue for the original destination in the case of the LOGTYPE macro (these 
macros and their functions are described in the chapter Defining Terminal and 
Line Control Areas ). The alternate destination specified in ALTDEST= may be 
the original destination. If the alternate destination queue is located in the 
message queues data set currently being reorganized, the unserviced message is 
written in Zone C. If any destination QCBs have assigned next header records in 
Zone B, a canceled header is written in this location, thus updating next header 
positions to the current zone. This prevents a new message from being sent to its 
alternate destination because its header is too far back (by definition, this is an old 
message). By the time that the end of Zone D is reached. Zone A is ready for 
reuse; all unserviced, uncanceled messages that were in Zone A have been copied 
into Zone C (if the queue for the alternate destination is located in this data set) 
or copied into another data set. When Zone A is reached, its contents are overlaid 
with incoming messages. The cycle is repeated as each of the four loadpoints is 
reached. 

When a zone is reorganized and the unserviced messages for a particular destina- 
tion located in that zone are requeued for their alternate destination, they are 
assigned a message priority equal to or less than their original priority as specified 
for the alternate destination and are placed in its FEFO queue. For instance, if 
the original destination message had a priority of 8, and the available priority 
levels for the alternate destination are 9, 7, 5, and O, the message will be requeued 
with a priority level of 7. If the alternate also had a priority level of 8, the original 
message will be requeued at the same priority level. Messages are sent in the 
FEFO sending order usually in effect for messages having the same priority on a 
destination queue (see the discussion of message priority and queuing in the 
chapter Defining Terminal and Line Control Areas). Whether or not this 
modified message priority and sending scheme for requeued messages turns out to 
be an asset or a Uabihty to the reusable disk user depends upon his application. 

Note: When messages are moved in a zone reorganization, sequential order- 
ing is not maintained. 

The advantages of reusable disk queuing have already been mentioned. When the 
reorganization scheme just outlined is considered, certain disadvantages become 
evident: 

1 . The disk activity required during data-set reorganization may result in longer 
response times than would occur if nonreusable disk were used. Each message 
that is requeued must be read into main storage and rewritten in a message 
queues data set, and each dummy canceled message must be written from main 
storage into the data set on reusable disk. The longer that messages remain 
enqueued on the disk before being sent, the more likely it becomes that they 
will have to be reread and rewritten. Messages are more hkely to Unger in a 
reusable disk queue: when the transmission priority for the nons witched line to 
their destination is equal or receive rather than send (see the discussion of 
transmission priority in the chapter Defining Terminal and Line Control 
Areas ); when many stations are assigned to the same line; when traffic to a 
destination is heavy; when not enough CPBs are specified; when the destina- 
tion station is a start-stop rather than a BSC terminal; when the destination is 
an application program whose data sets are not open; and when a destination 
station on an Inward WATS line calls the computer infrequently. Terminal 
reliability is also a factor. If messages for a station must be intercepted by an 
operator command or by a HOLD macro because the station is inoperative. 



1^, 



i 



94 OS/MFT and OS/MVT TCAM Programmer's Guide 



response time will lengthen as the number of intercepted messages increases; 
this effect is compounded if the queue for the alternate destination specified for 
an intercepted station is also located in the reusable disk data set. 
2. TCAM's capability of retrieving messages that have already been sent (as 
described in the Message Retrieval section of the chapter Writing TCAM- 
Compatible Application Programs ) is limited when reusable disk queuing is 
used, because the original copy of a transmitted message is eventually overlaid 
by another incoming message. 

A serious problem may arise if a data set on reusable disk becomes full, that is, if 
TCAM's reusability routine is called to service a new zone, but has not yet 
completed servicing the previous zone. If there are more messages to be sent to 
alternate destinations than the reusability routine can handle, active disk records 
may be overlaid; when this happens, a logical read error occurs and TCAM 
terminates abnormally with a system ABEND code of 045 and with a code of 02 
or 03 in register 15. 

Heavy usage of reusable disk may be the result of either a sudden surge of incom- 
ing traffic for this queue type, or an accumulation of a large number of messages 
that must be routed to alternate destinations because their primary destinations 
are unable to accept them. 

In an attempt to prevent the need for abnormal closedown, TCAM requests 
cessation of incoming traffic, permitting send operations to have temporary 
priority to clear the data set of unsent messages. When the overlay danger is past, 
normal receive operations are resumed. If the temporary halt of receive opera- 
tions cannot prevent overlay of active records, the ABEND is issued. 

To reduce the frequency of this slowdown, the following steps may be taken: 

a. Format a larger reusable disk data set. As a rule of thumb, the data set should 
be at least large enough so that the longest message to that data set will span 
less than a fourth of the disk (less than one of the four zones). Otherwise, the 
internal TCAM zone reorganization routine may be unable to transmit unsent 
messages to their alternate destinations (because a zone for the abnormally 
long message has been overlaid, resulting in loss of header information needed 
to send this message to its alternate destination). 

b. Spread reusable disk data sets over several volumes (and ideally over several 
channels), thereby facilitating more rapid servicing of the zones by TCAM's 
reusability routine. 

c. If it is likely that a station will be intercepted or otherwise unable to receive for 
an appreciable percentage of the time, do not locate the destination queue for 
that station on reusable disk. 

d. To avoid trapping unsendable messages queued for a defective station, do not 
specify a station as its own alternate destination. 

e. To avoid accumulating messages queued to switched stations, exercise care in 
the specification of the DIALNO= and CLOCK= operands on the 
TERMINAL macro. By coding DIALNO=NONE, you prohibit the CPU from 
initiating a call to send messages to this station. The CLOCK= operand 
restricts the CPU to a single call every 24 hours. 

f . Consider the number of priority levels specified in the TERMINAL macro for 
each destination queue. Each priority level requires one record for the next 
header being sent to that destination. Thus, the more priorities that are as- 
signed, the larger the reusable disk needs to be. The number of priorities in the 
system should be less than one-eighth the total number of records on the disk. 
To determine the number of priorities, the following formula can be used: 



Defining the MCP Data Sets 9 5 



Nonreusable Disk Queues 



T > 8(x + y) 

where T is the total number of records on the disk, x is the total number of 
TERMINAL, TPROCESS, and LOGTYPE macros coded in the terminal table, 
and y is the number of levels specified in every LEVEL = operand for every 
TERMINAL macro defined. 

g. Receive priority with too short an interval can cause messages to accumulate 
and create additional overhead. 

h. Finally, remember that the busier the lines, the larger the reusable disk data set 
should be; turnaround time for message transmission is adversely affected if the 
data set is not large enough for high-density message traffic. 

When using initiate mode or program-controlled interruption for input, be aware 
of the possibility that the first segment of a very long message can be overlaid 
before the last segment is received. 



For a TCAM MCP that must run continuously for an extended period of time 
with fairly heavy message traffic, the user would have to allocate more disk space 
if he used nonreusable queuing than he would if he used reusable queuing. In 
addition, a TCAM system using nonreusable disk queues must be closed down 
from time to time as the available space in the data set is exhausted. One great 
advantage that nonreusable disk queues have when compared with reusable disk 
queues is that system overhead is cut down during extended periods of high 
message traffic when nonreusable disk queuing is specified, because the data-set 
reorganization described above for reusable disk queues is not performed for 
nonreusable disk queues. Nonreusable disk queuing is attractive for applications 
in which many messages will remain enqueued for a long period of time before 
being sent; general criteria for estimating this likelihood are given above in the 
discussion of reusable disk queues. 



Main-Storage Queuing 



When a certain percentage of the records in a message queues data set on non- 
reusable disk has been used, a flush closedown (defined in the chapter Activating 
and Deactivating the Message Control Program ) is initiated by TCAM. The 
threshold percentage is specified by the THRESH= operand of the message 
queues DCB macro (described below) and should be based on a consideration of 
the maximum number of message units that will result from messages entered at 
stations and the number of units on the disk data set. If the data set fills before 
closedown is finished and wraparound of the nonreusable disk overlays the first 
record, the TCAM MCP will terminate abnormally with a system code of 045 and 
a value of 01 in register 15. Following the flush closedown, the data set must be 
reformatted (using the lEDQXA utility described in the chapter System 
Preparation ), and the system may be restarted by means of a cold restart. 



The main-storage message queues data set (if specified) is created at the time the 
INTRO macro is executed, when an area of main storage is allocated to the 
buffer-unit pool. The data set resides in the buffer-unit pool, which is described 
in the chapter Defining Buffers . Buffer units containing data directed to a 
destination queue in the main-storage data set are assigned directly to the appro- 
priate queue. Upon removal from the queue, the units are available for reuse. No 
data is moved iwhen units are placed on the queue; however, when the message is 
to be sent to its destination, it is copied from the enqueued units containing it into 
a buffer. The original copy is held in the queue until the message has been 
transmitted and any macros in the outmessage subgroup handling it have been 



i 



96 OS/MFT and OS/MVT TCAM Programmer's Guide 



given an opportunity to check the message error record for the message; this is 
done so that the message header may be retrieved from the queue, if necessary. 

Because data in main storage is obtained and manipulated more rapidly than data 
stored on disk, during periods of high message traffic, messages directed to 
destinations whose whose queues are located in main storage will be received 
much more rapidly than would be the case if the queues for these destinations 
were located on disk. Because allocation and deallocation of units for the main- 
storage data set is dynamic, the data set is essentially ''reusable." 

When a message queues data set is located in main storage without disk backup, 
sufficient main storage must be allocated to the data set to handle peak message 
traffic. The MSUNITS= operand of the INTRO macro specifies the maximum 
number of units that can be assigned at any one time to the main-storage message 
queues data set. If buffer units containing part of an incoming message are 
inserted into the destination queue, causing the number specified by MSUNITS= 
to be exceeded, bit 16 is turned on in all message error records in the system. The 
first unit of the buffer is placed in the queue; all the other units of the buffer are 
lost. If this was not the last buffer in the message, any error-handling macros 
(coded in the inmessage subgroup of the Message Handler for this line group) that 
test bit 16 of the message error record are activated. For example, the user might 
code a MSGGEN or ERRORMSG macro to advise the terminal operator or an 
application program that message segments are being lost because of a lack of 
available main-storage units. The operator or application program could then 
slow down incoming message traffic using appropriate operator commands or 
network control macros until sufficient main-storage units are available. If the 
segment rejected was the last segment, the entire message (except for the first 
unit) is lost; in this case the user may test bit 16 of the message error record when 
another message is handled by this or another Message Handler. 

The first unit of a message that is lost because of a lack of main-storage units is 
always enqueued in its proper destination queue. When this unit is processed by 
the outgoing group of the Message Handler for the destination station, bit 16 of 
the message error record for this message is turned on. In his outmessage sub- 
group, the user may code error-handling macros to test bit 16. For example, he 
might code an ERRORMSG macro that would return the unit to the originating 
station together with a request that this message be retransmitted. 

In the event that there is not even enough main-storage space available to permit 
the first unit of a message to be enqueued (that is, if enqueuing the unit would 
cause the value specified in the MSUNITS= operand to be exceeded), TCAM 
nevertheless enqueues the unit. In addition, TCAM refuses to accept any more 
incoming messages (these messages are not lost) until the number of units in the 
main-storage data set falls to or below the level specified by the MSMIN= 
operand of the INTRO macro. 

TCAM's only criterion in determining whether units are available for main- 
storage queuing is the number specified by the MSUNITS= operand of the 
INTRO macro. It is up to the user to specify a satisfactory number of main- 
storage units for his system. If he does not, and if no disk backup is provided, 
throughput will suffer because fewer incoming messages will be accepted, and 
some message segments may be lost. 

p TCAM provides the user of main-storage queues with a means of informing 

himself when the main-storage data set is in danger of running out of units. In the 



Defining the MCP Data Sets 97 



MSMAX= operand of the INTRO macro, the user may specify a percentage of 
his main-storage data set units (that is, a percentage of the number specified in the 
MSUNITS= operand of INTRO); when this percentage of units is enqueued, bit 9 
of all message error records in the system is set. The user may code a MSGGEN 
or ERRORMSG macro in his Message Handlers to check this bit and inform the 
operator or an application program to slow down invitation until a suitable 
number of enqueued messages have been sent to their destinations. Since mes- 
sages for inactive application programs are maintained on main-storage queues, 
the user may also activate the application program and allow those enqueued 
messages to be sent. The MSMIN= operand of INTRO also specifies a percent- 
age of the total number of units available for main-storage queuing. When the 
percentage of units enqueued in the main-storage data set falls below that speci- 
fied by MSMIN=, bit 8 is set on in all message error records in the system. The 
user may code a MSGGEN or an ERRORMSG macro in his Message Handlers to 
test this bit and inform the operator or an application program that there is no 
longer a shortage of main-storage units, so that normal invitation may be resumed. 

When the percentage of enqueued units falls below that specified by MSMAX=, 
bit 9 is turned off in all message error records. When the percentage of enqueued 
units rises above that specified by MSMIN=, bit 8 is turned off in all message 
error records. 

TCAM also permits the user (who has one or more destinations using main- 
storage-only queuing) to inform himself when a certain number of messages are 
queued for output to a specific destination. See the description of the THRESH = 
operand of the FORWARD macro for a more complete description of this facility. 

Neither the intercept function (see the description of the HOLD macro) nor the 
retrieve capabiHty (see the description of the POINT macro) can be used for 
messages queued in main-storage-only queues. The ERRORMSG and 
REDIRECT macros provide Umited retrieval capability when certain errors (such 
as transmission errors, as detected by the EOB checking f acihty provided by the 
STARTMH macro) occur. 

A message queues data set located in main storage without disk backup cannot be 
checkpointed; if the TCAM system closes down or fails, all data in the data set is 
lost. 

Instead of specifying a main-storage message queues data set with no disk backup, 
the user may specify a main-storage data set having backup on reusable or non- 
reusable disk. Main-storage queuing with disk backup combines advantages of 
disk and main-storage queuing, and avoids certain of the problems associated with 
the other queuing methods. Data directed to a main-storage queue with disk 
backup is never lost because of unavailability of main-storage units, and TCAM 
will accept messages when the main-storage data set is full. TCAM's message- 
interception and message-retrieval functions may be utilized, and closedown and 
restart of the system without loss of data is possible. Response time is better than 
with disk queuing, because most outgoing messages do not have to be read from 
disk. 

When main-storage queuing with disk backup is used, TCAM copies each unit 
arriving at a main-storage queue onto disk. Copying involves a movement of all 
data in the unit and a writing operation. When the number of units specified in 
the MSUNITS= operand of the INTRO macro is enqueued in main storage (when 
the main-storage queues will accept no more units), data is not lost as it is whe^n 



( 



98 OS/MFT and OS/MVT TCAM Programmer's Guide 



I 



main-storage-only queuing is specified; instead, the contents of incoming units are 
written directly onto disk. No bit in the message error record is set when main- 
storage units are exhausted, and invitation is not suspended. The user may code 
the MSMAX= operand of the INTRO macro to warn him that the number of 
units enqueued in main storage is approaching the maximum permitted, and he 
may use the MSMIN= operand of INTRO to inform him when the number of 
units enqueued in main storage has fallen to a safe level. 

Outgoing messages are sent from the main-storage queue when they are on this 
queue; otherwise they are brought in from disk and sent. When a message is sent 
out from main storage, its copy on disk is marked serviced. 

The TCAM intercept function (using the HOLD macro) and retrieve function 
(using the POINT macro) may be implemented when main-storage queuing with 
disk backup is used (where access is to the disk queues). 

Main-storage queuing with backup on disk uses more main storage than disk 
queuing and results in a longer response time than would be the case if main- 
storage queuing with no disk backup were specified (because each message must 
be completely copied onto disk before it can be sent to its destination). Yet this 
method of queuing combines many of the attractive features of the other methods, 
and for many applications it provides an acceptable compromise between the 
speed of main-storage-only queuing and the reliability of disk queuing. 

Specifying One or More Queuing Methods 

The user may specify up to three message queues data sets for his TCAM system. 
One of these- resides in main storage, another on reusable disk, while a third is 
located on nonreusable disk. Taken singly or in combination, these three possible 
data sets provide the five queuing methods discussed. For main-storage-only 
queuing, a main-storage data set is needed. Reusable and nonreusable disk 
queuing each require a data set. If the user wishes to implement main-storage 
queuing with reusable disk backup, he must define two data sets — one in main 
storage and the other on reusable disk. Two data sets are also required to support 
main-storage queuing with backup on nonreusable disk. 

A TCAM system having two message queues data sets, one in main-storage and 
one on reusable disk, will support three types of queuing: main-storage-only 
queuing, reusable disk queuing, and main-storage queuing with backup on reus- 
able disk. The type of queuing used for a particular message in this system 
depends upon the message's destination. The QUEUES = operand of the 
TERMINAL or TPROCESS macro defining a remote station or an appUcation 
program specifies the type of queuing for messages destined for that station or 
application program. In the system being considered, messages sent to a terminal 
whose TERMINAL macro specified QUEUES = MO would be queued in main 
storage only. Messages sent to a terminal whose TERMINAL macro specified 
QUEUES =DR would be queued on the reusable disk only. Messages sent to a 
terminal whose TERMINAL macro specified QUEUES = MR would be placed on 
a queue in main storage if possible, and would also be placed on a queue in the 
reusable disk data set. Such messages would be retrieved and sent from the 
main-storage queue, if possible, or from the disk queue. 

The number of data sets that must be defined depends upon the type of queuing 
desired, which in turn depends upon the application. As an example, consider a 
savings bank inquiry application in which short incoming messages (consisting 
perhaps of an account number, a transaction amount, and a transaction code) are 



Defining the MCP Data Sets 99 



sent to an application program, and long response messages are returned by the 
application program. The TCAM user with such an appHcation might wish to use 
main-storage-only queuing for the inquiry messages (since they are short), and 
disk queuing for the response messages (since they are long). In this way, he 
could take advantage of the speed of main-storage-only queuing for his short 
input messages without giving up the main storage required if main-storage 
queuing were used for his long response messages. To implement his queuing 
scheme, this user would have to define two data sets — one in main storage, and 
one on disk. 

CheckHsts follow for specifying the three types of message queues data sets 
supported by TCAM. are discussed elsewhere in this publication. Note that no 
DD statement or DCB macro is required in defining a main-storage message 
queues data set, but that both a DD statement and a DCB macro must be issued in 
defining a message queues data set on either reusable or nonreusable disk. The 
DCB macro for a message queues data set on disk and the DD statement for such 
a data set are described in the next two sections. 



Checklist for Main -Storage Data Set 



Macro 
DD Card 

INTRO 



Operand 



MSUNITS=integer 



Comments 

Specifies the maximum number of main-storage buffer units that 
may be used for queuing. 



INTRO 



MSMAX=integer 



integer is a percentage of the number of units specified in the 
MSUNITS= operand; when this percentage of units is enqueued 
in the main-storage message queues data set, a bit is set in each 
message error record in the system to warn the user that his data 
set is nearly full. 



INTRO 



INTRO 



MSMIN=integer 



DISK= 



|NO) 
\YESJ 



When the percentage of the number of units specified by the 
MSUNITS= operand falls below that specified by MSMIN=, a 
bit is set in every message error record in the system. This 
operand may be used to inform the user that his main-storage 
message queues data set is no longer crowded. 



Specify NO if no message queues data set is to be provided on 
disk. Specify YES if the system will have a message queues data 
set on disk. 



TERMINAL 

or 
TPROCESS 



QUEUES=^MR 

MN 



Code MO for each station or appUcation program with queues 
to be located in main storage only; code MR if backup is to be 
provided on reusable disk; code MN if backup is to be provided 
on nonreusable disk. 



( 



100 OS/MFT and OS/MVT TCAM Programmer's Guide 



Checklist for Reusable Disk Data Set 



Macro or 
DD Card 


Operand 


DD 

Statement 




Message 

Queues 

DCB 




INTRO 


DISK=YES 


INTRO 


CPB=integer 


TERMINAL 

or 

TPROCESS 


QUEUES=|DRl 
\MRf 



Comments 



One needed; see DD Statements for Message Queues Data 
Sets . 



One needed; see next section. 



Specifies the nonzero number of channel program blocks to be 
provided for transfer of data between buffers and the disk; see 
Specifying Channel Program Blocks in this chapter. 



Code DR for each station or application program with queues to 
be maintained on reusable disk only; code MR for queues to be 
maintained in main storage with reusable disk backup. 



Checklist for Nonreusable Disk Data Set 

Macro or Operand Comments 

DD Card 



DD 

Statement 




Message 

Queues 

DCB 




INTRO 


DISK=YES 


INTRO 


CPB= integer 


TERMINAL 

or 

TPROCESS 


QUEUES = J DN ) 
IMN) 



One needed; see DD Statements for Message Queues Data 
Sets. 



One needed; see next section. 



Specifies the nonzero number of channel program blocks to be 
provided for transferring data between buffers and disk; see 
Specifying Channel Program Blocks in this chapter. 



Code DN for each station or 

appUcation program with queues to be maintained on nonreusa- 
ble disk only; code MN for each station with queues to be main- 
tained in main storage with nonreusable disk backup. 



Defining the MCP Data Sets 1 1 



Message Queues DCB Macro 



The message queues DCB macro 

• defines a message queues data set residing on reusable or nonreusable disk; 

• specifies the location of the data set; 

• specifies the percentage of records in a nonreusable disk data set to be filled 
before a flush closedown is initiated; 

• is not issued for a message queues data set residing in main storage. 

The message queues DCB macro defines a data control block for a message 
queues data set. Parameters based on the keyword operands specified in the 
macro are included in the data control block. One message queues DCB macro is 
required for a message queues data set residing on reusable disk, and one is 
required for such a data set residing on nonreusable disk. The macro generates no 
executable code. 

The message queues DCB macro has the following format: 



Name 


Operation 


Operands 


diskdcb 


DCB 


keyword operands 



diskdcb 



Function: Specifies the name of the macro instruction and the name of the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order and are separated by 

commas with no intervening blanks. 

Notes : The operands for the message queues DCB macro instruction are described 

below. 

When a parameter can be provided by an alternate source, a symbol appears in the 
alternate source entry for the operand. When there is no alternate source (that is, 
the parameter must be specified by the operand), the alternate source entry states 
None . The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be provided at execution time by the data 

definition(DD) card for the data set. 

OE The value of the operand can be provided by the problem program any 

time up to and including the data control block exit at open time. 



PP The value of the operand can be provided by the user's problem 

program any time before the data control block exit at open time. 



i 



102 OS/MFT and OS/MVT TCAM Programmer's Guide 



DSORG=TQ 



MACRF=(G,P) 



DDNAIVfE=:ddnanie 



If DD is specified, OE or PP may also be used. OE is specified, PP may also be 
used. For information on providing parameters by DD, see DD Statement for 
Message Queues Data Sets . For information providing parameters by DD and 
OE, see Modifying the Data Control Block in the OS publication Data Man- 
agement Services . The section Processing Program Description , in the same 
publication, describes the data control block exit that can be taken when OE is 
specified. 

The formats of macro illustrations, the symbols used in them, and rules for the 
interpretation of operand descriptions are all provided in Appendix A . 



Alternate Source: None. 

Function: Specifies that the data set organization is that for the message queues 

or checkpoint data set. 

Default: None. This operand is required. 

Format: DSORG=TQ 



Alternate Source: None. 

Function: Specifies that access to the data set is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



OPTCD= 



{^} 



Alternate Source: DD, PP, OE. 

Function: Specifies the location of the data set. 

Default: None. This operand is required. 

Format: L or R. 

Notes: L specifies that the data set is to be on nonreusable disk. R specifies that 

the data set is to be on reusable disk. 



EXLST=nanie of list 



Alternate Source: PP. 

Function: Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This operand is required if user label, data control block, user ABEND, or 

block count exits are required. The list must start on a fuUword boundary. Its 

format and contents are shown in Data Management Services . The user ABEND 

exit is discussed in the last section of this chapter. 



Defining the MCP Data Sets 1 03 



THRESH=integer ^ 

Alternate Source: DD, OE, PP. ^ 

Function: Specifies the percentage of the nonre usable disk message queue 

records to be used before a flush closedown of the system is initiated. 

Default: For reusable disk queues, specification optional. For nonreusable disk 

queues, 95. 

Format: Unframed decimal integer. 

Maximum: 100 

Notes: This operand is meaningful for nonreusable disk queues only. 

DD Statements for Message Queues Data Sets 

One DD statement is needed for each disk message queues data set. The format 
of this DD statement is as follows: 

//ddname DD DSNAME=anyname,DISP=OLD 

where ddname is the name specified by the DDNAME = operand of the DCB 
macro for this data set, and anyname is the name of the data set as specified by 
the DSNAME= operand of the lEDQDATA DD card for the lEDQXA utility 
used to Preformat disk message queues. If the data set is not cataloged, the 
UNIT= and VOLUME= operands must be included in the DD statement for the 
disk message queues data set. 

The OPTCD= and THRESH = operands of the message queues DCB macro may 

be omitted from the DCB macro and specified at execution time by coding the ^ 

DCB parameter of the DD statement for the message queues data set; that is: {| 

DCB=(OPTCD= JlI ) 

PI 

or 

DCB=(THRESH=n) 

Both operands may be specified by coding 

DCB= ( OPTCD= Jl) , THRESH^n ) 

Fi 

These operands are explained in the preceding section. 

No DD statement is issued to define a message queues data set in main storage. 



Checkpoint Data Set 



The TCAM checkpoint facility makes records of the MCP environment from 
which restart can be made in case of closedown or system failure. This facihty is 
described in the section Using TCAM Service Facilities . 

The checkpoint data set consists of checkpoint records that are maintained and 
stored on a direct-access storage device. A DCB macro instruction must be issued 
to define the data control block for the checkpoint data set if the checkpoint 
facility is to be used. The DD statement associated with the new checkpoint data 
set must allot space for these records on the direct-access device used. The 
direct-access device may be either an IBM 23 1 1 Disk Storage Drive, an IBM 23 14 
Direct Access Storage Facility, or an IBM 3330 Disk Drive. 



c 



1 04 OS/MFT and OS/M VT TCAM Programmer's Guide 



chkptdcb 



keyword operands 



Checkpoint DCB Macro 

The checkpoint DCB macro 

• defines a checkpoint data set residing on a direct-access storage device. 

The checkpoint DCB macro has the following format: 



Name 


Operation 


Operands 


chkptdcb 


DCB 


keyword operands 



Function: Specifies the name of the macro instruction and the name of the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order and are separated by com- 
mas with no intervening blanks. 
Notes: The operands for the DCB for the data set are described below. 

When a parameter can be provided by an alternate source, a symbol appears in the 
alternate source entry for the operand. When there is no alternate source (that is, 
the parameter must be specified by the operand), the alternate source entry 
specifies None . The symbols have the following meanings: following meanings: 

Symbol Explanation 

DD The value of the operand can be omitted from the DCB macro and 

provided at execution time by the data definition (DD) card for the 
data set. 

PP The value of the operand can be provided by the user's problem 

program any time before the data control block exit at open time. 

OE The value of the operand can be provided by the problem program any 

time up to and including the data control block exit at open time. The 
formats of macro illustrations, the symbols used in them, and rules for 
the interpretation of operand descriptions are all provided in Appendix 
A. 



DSORG=TQ 



Alternate Source: None. 

Function: Specifies that the data set organization is for the message queues or 

checkpoint data set. 

Default: None. This operand is required. 

Format: DSORG=TQ 



Defining the MCP Data Sets 1 05 



IVIACRF=(G,P) 



DDNAME=ddname 



OPTCD=C 



EXLST=address 



BLKSIZE=number 



Alternate Source: None. 

Function: Specifies that access to the data set is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Alternate Source: PP, OE, DD. 

Function: Specifies that the data set is for checkpoint records. 

Default: None. This operand is required. 

Format: OPTCD=C 



Alternate Source: PP. 

Function: Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This Ust must be provided if user label, data control block, or user ABEND 

exits are required; it must start on a fuUword boundary. The format and contents 

of the list are shown in the Data Management Services publication. The user 

ABEND exit is discussed in the last section of this chapter. 



Alternate Source: DD 

Function: Specifies the size in bytes of the environment checkpoint records on 

disk. 

Default: 300 

Format: Unframed decimal integer. 

Minimum: 300 

Maximum: 3520 

Notes: If a number less than 300 or greater than 3520 is specified, 300 or 3520 

respectively is used, and a message notifying the programmer is generated on the 

system output device. A larger record size may use disk space more efficiently, 

but the work area would take up more main storage. These two factors must be 

taken into account to arrive at the best BLKSIZE for a given application. 



DD Statement for the Checkpoint Data Set 

One DD statement must be issued for the checkpoint data set. If DISP=NEW is 
coded, this statement must allocate space on DASD for all records in the check- 
point data set. A formula for allocating sufficient space is given in How to Get 
the TCAM Checkpoint Facility in the chapter Using TCAM Service Facilities . 
The DISP= parameter must be coded DISP=OLD for a warm restart and may be 
coded either DISP=OLD or DISP=NEW for a cold restart. If DISP=NEW is 
coded, STARTUP=CY is assumed for the INTRO macro instruction (or 



( 



106 OS/MFT and OS/MVT TCAM Programmer's Guide 



Log Data Sets 



STARTUP = CI Y, if I coded in the STARTUP = operand), regardless of what is 
coded for STARTUP = at assembly time or at WTOR response time. (The 
disposition parameter of DISP= also may be coded.) Any incremental quantity 
requested on the SPACE= parameter is ignored. 

The OPTCD= operand of the checkpoint DCB macro may be specified at execu- 
tion time by coding the DCB parameter of the DD statement for the checkpoint 
data set as DCB=(OPTCD=C). 

A typical DD card used for initial allocation is: 

//TPCHKPNT DD DSNAME=CPDS , UNIT-23 1 1 , * 

// V0LUME=SER=1 1 1 1 1 1 , * 

// SPACE=(TRK,( 3 ) ), * 

// DISP=(NEW,CATLG) 

Note: The step containing the DISP=(NEW,CATLG) operand must terminate 
normally for the deallocation routine to perform the catalog function. If 
such a step is halted by SYSTEM RESET or Master Check, the catalog is 
not updated. The next use of the data set, with DISP=^OLD coded, must 
either supply the UNIT= and VOL=SER= operands, or the name must have 
been entered into the catalog using the CATLG command of the 
lEHPROGM system utility. 

A typical DD card used for the same (cataloged) checkpoint data set after initial 
allocation is: 

//TPCHKPNT DD DSNAME^CPDS , DISP=OLD 

The data set does not have to be cataloged. If it is not cataloged, the data set is 
allocated by specifying DISP=(NEW,KEEP), and subsequent uses of the data set 
must contain the UNIT= and VOL=SER= keyword operands to provide the 
information that would otherwise be in the catalog. 

Note: There is no utility job to format a checkpoint data set. It is format- 
ted by OPEN at each cold restart. 



A log data set consists of messages or message segments placed on a secondary 
storage device for accounting purposes. TCAM's support of the logging function 
is described in the Using TCAM Service Facilities chapter and in the descrip- 
tions of the LOG and LOGTYPE macros. The TCAM logging facility is optional. 

One log data set should be defined for each secondary storage device on which 
messages or message segments may be logged. A log data set is defined by a 
BSAM DCB macro that is issued with the DCBs defining the line group data sets, 
the message queues data sets, and the checkpoint data set. The BSAM DCB 
macro is described in the Supervisor and Data Management Macro Instructions 
publication. 



Defining the MCP Data Sets 1 07 



User ABEND Exits 



In the BSAM DCB macro for a log data set, the user should code the following 
operands: 

Operands Comments \ 

DSORG=PS 

MACRF=W 

DDNAME=symbol 

BLKSIZE=keylen Replace keylen with the value specified 

in the KEYLEN= operand of the INTRO 

macro. 
RECFM=F 
NCP=integer Replace integer with the maximum number 

of buffer units that may appear in a 

buffer. 

The SYNAD= address operand of the BSAM DCB macro, where address is the 

name of a user-specified, error-analysis routine to be given control when an 

uncorrectable I/O error is detected, should also be coded. The error routine must 

conform to the standards set forth in the discussion of this operand in the 

Supervisor and Data Management Macro Instructions publication. Upon return 

from the error-analysis routine, the log function continues as if no error had been 

encountered. All indications of the I/O error must be removed from the DCB, 

(that is, reset the first two bits of the IFLGS field of the data control block to 

zeros — see the EXCP macro instruction in the System Programmer's Guide); if an 

I/O error is still indicated the MCP will terminate abnormally when the next 

WRITE is issued. The format of the BSAM DCB is described in the System 

Control Blocks publication. If this operand is not specified, the MCP terminates 

abnormally when a permanent I/O error occurs during the logging operation. The 

UNIT= parameter of the DD statement associated with each log DCB macro 

should specify the address of the appropriate secondary storage device. ,f 

The DCB macros for the Une group data sets and for the message queues data sets 
permit specification of a user-written routine to be given control if an OPEN 
macro fails to open the data set for which the DCB macro is coded. The user 
routine is specified by coding a special entry in the problem-program exit Ust 
named in the EXLST= operand of the appropriate DCB macro. (The format and 
contents of the problem-program exit list are shown in Data Management 
Services .) The special entry, called the user ABEND entry, consists of a one-byte 
code of X*OE' followed by the three-byte address of the user routine. 

If the OPEN macro for a particular data set fails to execute properly, and if a user 
ABEND entry is included in the EXLST= operand of the DCB macro for the data 
set, the user routine is given control. The user routine should save and restore 
registers. When control is passed to the user routine, the general registers contain 
the following information: 



( 



108 OS/MFT and OS/MVT TCAM Programmer's Guide 



Register Contents 

Error code 

1 Options available to the user ABEND routine 
2-13 Contents before execution of the OPEN macro 

14 Return address (must not be altered by the exit routine) 

1 5 Address of user-routine entry point 

The error code, which occupies the right-hand byte of register (the other three 
bytes are set to 0) tells the user the reason why the OPEN failed. Possible error 
codes and brief explanations are described in the publication TCAM Level 4 
Component Release Guide. 

The error code is also included in a message directed to the system console when 
the OPEN fails. This message, which is sent even when no user ABEND routine 
is specified, has the following format: 

IED008I TCAM OPEN ERROR xxx-y IN DCB dcbname descriptor 

Here, xxx-y is the code referred to in the list of error codes, dcbname is the name 
of the DCB macro for the data set that could not be opened properly, descriptor 
is a single word describing the type of error. This message is discussed in the 
TCAM Level 4 Component Release Guide document. 

The following instructions may be coded in the user ABEND routine to return 
control to TCAM: 

L 13,4(13) 

RETURN ( 14, 12 ),T,RC=( 15 ) 

If an OPEN macro fails to execute properly and no user ABEND exit is provided, 
TCAM issues an ABEND macro to terminate the MCP task. 

Before control is passed to the user ABEND routine, TCAM sets the bits in the 
right-hand byte of register 1 to indicate to the ABEND routine what courses of 
action it may take. The code in register 1 indicates possible user options; the 
TCAM Open routines are set up to work properly if any of the courses of action 
indicated by the code in register 1 are taken. It is recommended that the user 
ABEND routine restrict its activities to the options indicated in register 1 . Possi- 
ble user ABEND alternatives and the codes associated with them are shown 
below. 

Code in 

Register 1 Permissible User Options 

X*03' 1. You can abnormally terminate the MCP job — either by 

issuing an ABEND macro in your subroutine, or by placing 
a return code of X'02' or higher in the right-hand byte of 
register 15 and returning control to TCAM. 
2. You can tell the TCAM Open routine to make no further 
attempt to open this data set, but to pass control to the next 
instruction in the MCP. This is done by placing a return 
code of X'OO' in the right-hand byte of register 15 and re- 
turning control to TCAM. In this case, your MCP will run 
with restricted capabilities, since it will not be able to use 
this data set. 



Defining the MCP Data Sets 1 09 



X'07' 1 . Same as Option 1 for X'03' code. 

2. Same as Option 2 for X'03' code. 

3. In activating the lines in a line group data set, a TCAM 
Open routine has found a Une on which there are stations 
incompatible with those found on a previous line within the 
same line group. (See Characteristics of a Line Group in 
the chapter Defining the MCP Data Sets for the common 
characteristics that stations and Hues in the same hne group 
must have.) When such a line is found, TCAM stops activat- 
ing lines in the line group. By placing a return code of X'OT 
in the right-hand byte of register 15 and returning control to 
TCAM, you direct the Open routine to open a modified Une 
group data set consisting of only those lines that had been 
activated when the hne having incompatible stations was 
encountered. In this case, messages directed to stations or 
lines that were not activated will be enqueued in a message 
queues data set, but will never be sent to these stations. 

If the user specifies a return code of X'OT in register 15 and the option code 
passed to him in register 1 was X*03', TCAM immediately takes the ABEND exit 
again; unless the user routine has code providing for this possibihty, a loop will 
result. 

For more information on the DCB exit hst and how it is specified, see Data 
Management Services. 



/I 



i 



110 OS/MFT and OS/MVT TCAM Programmer's Guide 



Activating and Deactivating the Message Control Program 

This chapter describes how to start and restart the TCAM Message Control 
Program, how to initiaUze and activate the TCAM data sets, and how to close 
down the TCAM MCP. 

Starting and Restarting TCAM 

The Message Control Program is assembled, link-edited, and executed like any 
other problem program running under an OS system. Sample Job Control Lan- 
guage for assembUng, Unk-editing, and executing the MCP is given in the chapter 
Putting the MCP Together. 

The TCAM MCP may be started or restarted by placing the job control state- 
ments for the EXECUTE step in the card reader and activating an OS 
Reader/Interpreter (by a START command issued at the system console) to read 
the JCL into the system. Another way to start or restart the MCP is to issue a 
START command naming a cataloged procedure that causes the MCP to be 
executed. The chapter on putting the MCP together contains sample code and job 
control statements for implementing both types of start-up. The various types of 
restart available to the TCAM user are described in the TCAM 
Checkpoint /Restart Facility section of the chapter Using TCAM Service 
Facilities . 

Initialization and Activation 

The INTRO, OPEN, and READY macros are issued as a group; together they 
constitute the data-set initialization and activation section of the Message Control 
Program. This section must precede the Message Handler sections of the MCP 
(see the chapter Pw/Zmg the Message Control Program Together). When the 
INTRO, OPEN, and READY macros have been executed, the TCAM system is 
ready to handle message traffic. 

As the first macro executed in the Message Control Program, INTRO expects to 
get control from OS job management. INTRO estabHshes standard entry linkage 
with job management, chains save areas, provides addressability, and saves the 
start parameter Ust pointer. To insert user-written code (which must not contain 
any TCAM macros) before INTRO, the Message Control Program (that is, the 
code beginning with INTRO) should be called as a subroutine of the inserted user 
code; register 15 should contain the address of INTRO, register 14 the address to 
which the MCP returns upon termination of TCAM, register 13 the address of a 
standard 18-word save area, and register 1 the start parameter Hst pointer as 
originally passed in register 1 from job management. 

If the user desires to refer to the PARM field of the EXEC job control statement, 
he may either use the register 1 pointer as passed by job management (before 
INTRO execution) to find the PARM field; or (after INTRO execution) this same 
value (in register 1) is stored by INTRO in a local constant area, a fullword tagged 
lEDSPLPT. 

The INTRO macro also creates the address vector table (which is the primary 
control block of the TCAM system) wherein many system variables are defined. 
When INTRO is executed, it optionally provides for dynamic redefinition of many 
of these system variables by interpreting the operator's response to a WTOR 
message. Once the system variables are defined in the address vector table. 



Activating and Deactivating the Message Control Program 111 



INTRO continues with system initialization, creating buffers and trace tables, and 
formatting control blocks. 

The OPEN macro completes the initialization and activation of the TCAM data 
sets. The TCAM data sets that must be activated in the MCP by OPEN macros 
are those for the message queues, the line groups, the message logs, and check- 
point. 

Each data set that is used by the MCP can be opened by a separate OPEN macro, 
or all data sets of the same type (for example, all line group data sets) can be 
opened with one OPEN. If used, the message queues data sets must be opened 
first, and the checkpoint data set must be opened next. Opening a line group data 
set causes all lines in the line group to be prepared for operation; the lines option- 
ally may be prepared for message transmission at this time, or activation may be 
deferred until later (the line is opened idle and later started by the STARTLINE 
operator command). 

The READY macro must be the last instruction in the initialization and activation 
section of the MCP. When READY has executed, the system is prepared to 
handle message traffic. The expansion of this macro causes a branch to the 
internal routine that supports the MCP, where receipt of the first message is 
awaited. When the first message is received (either from a terminal or an applica- 
tion program), control is transferred to the MH section of the MCP for handling 
the message. 

Once the MH sections are initially entered after the execution of the READY 
macro, execution of user-specified code in the MCP is restricted to the Message 
Handlers; that is, the MH sections are continually reentered to handle messages /f 

entering and leaving the computer as long as the MCP is active. Accordingly, any ^ 
user code must either be within or be branched to from a Message Handler. User 
code cannot branch between Message Handlers. (See the User Code in a 
Message Handler section of the chapter De5/^«/«g the Message Handler.) 

For a sample MCP initialization and activation routine, see the last section of this 
chapter. 

In addition to initial start-up of the TCAM system, as described above, TCAM 
provides for three types of restart following system closedown or failure. These 
are discussed in Restart of the chapter Using TCAM Service Facilities. 



( 



112 OS/MFT and OS/MVT TCAM Programmer's Guide 



INTRO 



The INTRO macro 

• creates the address vector table (the primary control block in the TCAM 
system); 

performs the bulk of TCAM system initialization; 

estabUshes addressabihty and entry linkages for the Message Control Program; 
specifies the name of the Message Control Program; 

specifies the number of channel program blocks to be provided for transferring 
data between buffer units and queues maintained on disk; 
specifies the maximum number of command input blocks that may be used at 
any one time to contain operator commands entered at the system console; 
identifies the primary operator control terminal; 
specifies a character string used to identify operator commands; 
specifies the size of buffer units; 

specifies the maximum number of units that may be assigned to a main-storage 
message queues data set; 

provides the user with a means of determining when his main-storage message 
queues data set is nearly full, and when this condition of impending fullness has 
abated; 

identifies the station or application program to which messages having an 
invaUd destination are to be forwarded; 

specifies which user registers are to be saved when in-Hne user code is located 
in an inheader or outheader subgroup that may handle multiple-buffer headers; 
specifies the length of the system interval; 
specifies the interval between environment checkpoints; 
specifies the number of environment checkpoint records to be retained at any 
one time; 

provides system optimization by specifying that unnecessary options are to be 
omitted; 

specifies the type of restart to be performed following system closedown or 
failure; 

specifies a password that must be coded in certain appUcation-program macros 
that affect operation of the MCP; 
provides for inclusion of various debugging facilities; 

specifies whether a special operator awareness message is to be displayed at the 
primary operator control station whenever a station fails to respond to polling. 

• specifies the number of concurrent broadcast requests, the number of common 
data areas, and the size of each data area. 

TCAM reUes upon the INTRO macro to supply information for defining and 
initializing a variety of TCAM functions. The operands of INTRO provide 
information concerning data-set definition (DISK-, CPB=, MSUNITS=, 
MSMAX=, MSMIN=), buffer definition (KEYLEN=, LNUNITS=), the opera- 
tor control facility (CIB=, PRIMARY=, CONTROL==), the Message Handlers 
(DLQ=, USEREG=), line control (INTVAL=), the TCAM checkpoint/restart 
facility (CPINTVL=:, CPRCDS=, STARTUP=^, RESTART «=, CKREQS==:), 
system optimization (CPB=, DISK=, FEATURE=, LINETYP=:), network 
configuration (PASSWD=), debugging aids (TRACE=, TREXIT=, DTRACE=:=, 
CROSSRF=, TOPMSG=, COMWRTE=), and the on-line test facility 
(OLTEST=). Sections devoted to each of the above topics are located elsewhere 
in this publication. The user may read the description of the INTRO macro for 
general information before he is f amiUar with the TCAM functions to which the 
operands refer, but he should not attempt to code INTRO operands until he has 



Activating and Deactivating the Message Control Program 113 



read the discussion of the particular function he wishes performed. In general, the 
following operand descriptions will refer the reader to the discussions of the 
functions of the operands. 

TCAM provides the user with the abihty to replace, at INTRO execution time, 
values specified at assembly time by certain operands of the INTRO macro, and to 
provide values for INTRO operands that were omitted at assembly time. 

At the time INTRO is executed, it may cause the following WTOR message to 
appear on the system console: 

nn IED002A SPECIFY TCAM PARAMETERS 

This WTOR message is issued only if at least one of the following operands is 
omitted from the INTRO macro: STARTUP=, KEYLEN=, LNUNITS=, and (if 
DISK=YES is coded in INTRO) CPB=. If these operands are all coded in the 
INTRO macro, no WTOR message is issued at execution time. 

If the WTOR message IED002 is displayed, its first appearance is preceded by 
another message: 

IED001I TCAM JOB job name, stepname, procstepname 
ADDRESS OF AVT xxxxxxxx. 

This AVT address may be used by the operator to display (or modify, according to 
the system programmer's instructions) areas of the Message Control Program 
during the WAIT for the WTOR reply. 

After the TCAM system issues the WTOR message, it waits for a user response to 
be entered at the system console. The user has two options in responding: he 
may either enter response keywords (as shown in the '^response keyword" line in 
the list of INTRO operands), or he may enter INTRO operand names (as shown 
in the header Hne in the Hst of operands) together with appropriate values. Sev- 
eral keywords or operands, separated by commas or vertical bars ( | ) may be 
coded in one response. Responses may be entered in upper- or lowercase letters. 
They will be translated into uppercase automatically. Each response is Umited to 
41 characters. After a response has been entered, TCAM re-issues the WTOR 
message and continues to issue it after each response is entered until the user 
indicates, by coding U at the end of a response, that he has nothing more to 
specify. If the user codes U and has not yet specified values for STARTUP=, 
KEYLEN=, LNUNITS=, or (if DISK=YES is specified in INTRO) CPB= either 
in the INTRO macro or in a response to the WTOR message, TCAM prompts him 
with the following message: 

nn IED004A REQUIRED PARAMETER MISSING . SPECIFY operand 

where operand is the name of the missing INTRO operand. 

An error in specifying a response keyword or operand (such as an invaUd response 
keyword, an invaUd operand, or an invalid value with a response keyword) causes 
an error message to be printed at the console. The operator may respecify the 
response keyword or operand when he receives such a message. An error in one 
response keyword or operand prevents interpretation of any keywords in the same 
response to the right of the keyword in error. A response keyword or operand 



( 



1 14 OS/MFT and OS/MVT TCAM Programmer's Guide 



may be coded more than once in the sequence of WTOR responses; the last value 
specified applies. 

Example: 

The following WTOR messages and responses occur at INTRO execution time for 
a user who has omitted the STARTUP= and LNUNITS= operands from his 
INTRO macro. The user specifies LNUNITS=, MSMIN=, MSMAX=, 
CPRCDS=, and CONTROL=, but forgets to specify STARTUP= (a required 
operand) and is prompted for this operand. 

message: 00 IED002A SPECIFY TCAM PARAMETERS 

response: r 00, ' B=2,MsMIN=80 X=95,E=5' 

message: 00 IED002A SPECIFY TCAM PARAMETERS 

response: r 00 , ' CONTROL=OPcONT, u ' 

message: 00 IED004A REQUIRED PARAMETER' MISSING . SPECIFY STARTUP^ 

response: 00 , ' s=c , u ' 

Note: // no response keyword is shown for a particular operand, the value 
for that operand may not be specified at INTRO execution time. 

INTRO has the following format: 



Name 


Operation 


Operands 


[symbol] 


INTRO 


keyword operands 



^ symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



PROGID=characters 



i 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order according to assembler 

language conventions. 

Notes: The operands for the INTRO macro are described in the following Ust. 

This list also shows the one-character response keywords that may be substituted 

for the operand names in responses to the WTOR message SPECIFY TCAM 

PARAMETERS sent to the system master console at INTRO execution time. 



Response Keyword: None. 

Function: Specifies the name of the Message Control Program. 

Default: None. Specification optional. 

Format: One to 230 unframed characters with no embedded blanks or commas. 

Notes: TCAM inserts this name in a DC C* characters ' field located in the MCP. 

In a dump, this name appears in the EBCDIC field at the right of each page of the 

listing and identifies the beginning of executable code for the MCP. If this 

operand is omitted, no name is assigned to the MCP. 



Activating and Deactivating the Message Control Program 115 



DISK= /no I 
|YESr 



Response Keyword: None. 

Function: Specifies whether any of the message queues data sets defined for this 

MCP are located on a direct-access secondary storage device. 

Default: DISK=YES 

Format: YES or NO. 

Notes: DISK = YES is coded if any of the message queues data sets are located on 

disk. DISK=NO is coded if no message queues data sets are located on disk. For 

further information, see Message Queues Data Sets in the chapter Defining 

Data Sets. 



V- 



CPB= C integer I 



Response Keyword: D= 

Function: Specifies the number of channel program blocks to be provided for 

transferring data between buffer units and message queues maintained on disk. 

Default: CPB=0 

Format: Unframed decimal integer. 

Maxim um: 65535 

Notes: One CPB is involved in transferring the data from one unit to disk, or in 

filling one unit with data from disk. See Specification of Channel Program 

Blocks in the chapter Defining Data Sets . 

If DISK=NO is coded, this operand is ignored by INTRO, and both CPB= and 
D= are invaUd responses at INTRO execution time. 



CIB= r integer) 

Response Keyword: C = 

Function: Specifies the maximum number of command input blocks (ICBs) that 
can be utilized at any one time in the TCAM system. 
Default: CIB=2 

Format: Unframed decimal integer. 
Maximum: 255 

Notes: CIBs are buffer-like areas used to contain operator commands entered at 
the system console. Space for them is allocated dynamically when needed, and the 
main-storage space assigned to a CIB. is freed once the operator command con- 
tained within the CIB has been processed. Only one CIB need be specified for 
operator commands entered from the system console. However, more than one 
CIB should be specified if the user anticipates processing simultaneously more 
than one operator command entered from the console. If an attempt is made to 
enter an operator command from the system console when the maximum number 
of CIBs are present already in the system (because that many operator commands 
from the system console are now being processed), the message being entered is 
rejected by TCAM. 

COIVllVIBUF=(integerl, integer!, integer3) 

Response Keyword: None. 

Function: Specifies the number of concurrent broadcast requests, the number of 

common data areas, and the size of each data area for 3670 terminals that receive 

broadcast messages. 

Default: None. Specification optional. 



( 



1 1 6 OS/MFT and OS/MVT TCAM Programmer's Guide 



Format: Unframed decimal integer greater than zero. 
Maximum: 65535 for each integer. 

Notes: integer 1 specifies the total number of concurrent broadcast requests. This 
number should equal the maximum number of lines that could concurrently have 
outstanding COMMBUF requests, multipUed by the number of unfulfilled 
COMMBUF requests permitted on a line (see the COMMBUF macro descrip- 
tion), integer! specifies the total number of data areas to be generated, integers 
specifies the size of each data area; the data area size must include a 6 byte work 
area required at the COMMBUF macro and must be a multiple of four. In the 
inheader or inbuffer subgroups, the COMMBUF macro should be issued naming a 
TLIST macro and specifying the maximum number of broadcast operations that 
may be scheduled on a line at any given time. 



PRIMARY= rtermname^ 
{ SYSCON } 



Response Keyword: P= 

Function: Specifies the name of the station or application program to be used as 
the primary operator control station. 
Default: PRIM ARY= SYSCON 

Format: termname or SYSCON. termname is the name of a station or applica- 
tion program (defined by a TERMINAL or TPROCESS macro). If a station 
name is specified, the station not be on a switched line, and it must be able to 
enter and to accept messages. 

Notes: SYSCON is the name of the system console. The functions of the primary 
operator control station are given in The Operator Control Facility section of 
Using TCAM Service Facilities. 



If termname is changed by a CPRIOPCL operator command, execution of a warm 
or continuation restart causes the value that was specified in the macro to be 
overridden by the value specified by the last CPRIOPCL command executed 
before closedown or failure. 



CONTROL= (characters I 



Response Keyword: L= 

Function: Specifies the character string used to identify each operator command 

as such to TCAM. 

Default: CONTROL=0 

Format: One to eight unframed characters with no embedded commas or blanks. 

Notes: CONTROL=0 indicates that no character string is being specified; it is 

valid only if all operator commands are to be entered at the system console. 



KEYLEN=integer 



\ 



Response Keyword: K= 

Function: Specifies the size of a buffer unit. 

Default: None. This operand is required. 

Format: An unframed decimal integer greater than 34. 

Maximum: 255 

Notes: GuideUnes for coding this operand are given in the chapter Defining 

Buffers . This chapter should be thoroughly understood before KEYLEN= is 

specified. If disk queuing is used, integer must be identical to unitsize as specified 

in the DCB=(KEYLEN=unitsize) parameter of the lEDQDATA DD statement 

for the lEDQXA utility program used to preformat the disk queues. 



Activating and Deactivating the Message Control Program 117 



UNITSZ=integer 



LNUNITS=mteger 



1VISUNITS= 



{» 



integer 1 



A buffer must be large enough to accommodate the larger of: 

a. a header prefix (30 bytes) plus the maximum number of reserve characters 
specified for the first buffer by the RESERVE = operand of any line group 
DCB macro or PCB macro, plus three bytes, or 

b. a text prefix (23 bytes) plus the maximum number of reserve bytes specified for 
buffers other than the first by the RESERVE= operand of any line group DCB 
macro or PCB macro, plus three bytes. 



Response Keyword: K= 

Function: Specifies the size of a buffer unit. 

Default: None. If KEYLEN= is specified, this operand must be omitted. If 

KEYLEN= is not specified, this operand is required. 

Format: An unframed decimal integer greater than 34. 

Maximum: 255 

Notes: This operand is an alternate spelling of the KEYLEN= operand. Either 

form, but not both, may be specified. 



Response Keyword: B= 

Function: Specifies the number of buffer units that may be used in building 

buffers to contain incoming and outgoing message segments. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 

Notes: Guidelines for coding this operand are given in the chapter Defining 

Buffers. 



Response Keyword: M= 

Function: Specifies the maximum number of buffer units that may be assigned to 
the main-storage message queues data set at any one time. 
Default: MSUNITS=0 
Format: Unframed decimal integer. 
Maxim um : 65535 

Notes: Guidelines for coding this operand are given in the discussion of main- 
storage message queues data sets in the chapter Defining the MCP Data Sets . 

This value is added to that specified for LNUNITS= to determine the total 
number of units in the buffer-unit pool. 

If MSUNITS=0 is specified or assumed, the expression M= may not be entered in 
the WTOR response at INTRO execution time. Therefore, if a main-storage 
message queues data set is desired, MSUNITS= must be coded with a nonzero 
integer, even if the value specified is to be overridden at INTRO execution time 
by an M= expression. 

Either MSUNITS= must be nonzero or DISK= YES must be coded. 



( 



1 1 8 OS/MFT and OS/MVT TCAM Programmer's Guide 



IVISIV1AX= 



( integer ^ 



!V1SIVIIN= { integer 1 

{5« I 



DLQ 



= I entry I 

\5 i 



> 



Response Keyword: X= 

Function: Specifies the percentage of the number of units (specified by the 

MSUNITS= operand) to be enqueued on a main-storage message queues data set 

before a warning is provided that the data set is nearly full. 

Default: MSMAX=70 

Format: An unframed decimal integer greater than zero. 

Maximum: 100 

Notes: When this percentage of units is enqueued, bit 6 is set in each message 

error record in the system. This operand is discussed in greater detail in the 

section on main-storage message queues data sets in the chapter Defining the 

MCP Data Sets. 



Response Keyword: Y= 

Function: Specifies the percentage of the number of units enqueued on a message 

queues data set (specified by the MSUNITS= operand) below which a bit is set in 

every message error record in the system. 

Default: MSMIN=50 

Format: An unframed decimal integer. 

Maximum: 99 

Notes: The operand may be used to inform the user that his message queues data 

set is no longer crowded. The value specified for MSMIN= must be less than that 

specified for MSMAX=, otherwise, the INTRO macro does not execute. Values 

specified for MSMIN= (or MSMAX=) at INTRO execution time by means of a 

WTOR response are checked against the current value of MSMAX= (or 

MSMIN=) if specified, to ensure that this rule is not broken. If the rule is broken, 

the value specified in the WTOR response is rejected and an error message is sent 

to the system master console informing the operator of this fact. The operator 

may then respecify the value. As an example, if MSMIN=95 and MSMAX=99 

are coded in the INTRO macro, at INTRO execution time the user should not 

code 

00 , ' MSMAX=90 , MSMIN=85 ' 

as a WTOR response, because the WTOR response is read from left to right and 
the new MSMAX value will be compared with the old MSMIN value and be 
rejected. If however, the user codes 

00, 'MSMIN=85,MSMAX=90' 

these values will be accepted since the new MSMIN value is less than the old 
MSMAX value, and the new MSMAX value is greater than the new MSMIN 
value, with which it is compared. 



Response Keyword: Q= 

Function: Specifies the name of the dead-letter queue to which messages with 

invalid destinations are sent. 

Default: DLQ=0 



Activating and Deactivating the Message Control Program 119 



Format: entry is the name of a station or application program as defined by a 
TERMINAL or TPROCESS macro. DLQ=0 specifies that no dead-letter queue 
is to be used. 

Notes: Dead-letter messages are messages having invalid destinations as deter- 
mined by a FORWARD macro. If a user-specified routine is coded for the 
EXIT= operand of the FORWARD macro, messages with invahd destinations 
may have the destination corrected. If both the DLQ= operand of INTRO and 
the EXIT= operand of FORWARD are omitted, dead-letter messages are overlaid 
and lost. 



USEREG* (integer) 



Response Keyword: None. 

Function: Specifies the number of registers to be saved when in-line user code is 

located in an inheader or outheader subgroup that may handle multiple-buffer 

headers. 

Default: USEREG=0 

Format: An unframed decimal integer. 

Maximum: 10 

Notes: For guidelines on specifying this operand, see the section User Code in 

a Message Handler. USEREG= specifies sequential registers, beginning with 

register 2. For instance, if USEREG=4 is coded, registers 2, 3, 4, and 5 are 

saved. 



INTVAL= 



i integer^ 



Response Keyword: 1= 

Function: Specifies the number of seconds in the system interval. 

Default: INTVAL=0 

Format: An unframed decimal integer. 

Maxim um : 65535 

Note's: The system interval is described in Maintaining Orderly Message Flow in 

the chapter Defining Terminal and Line Control Areas . 



Unless a nonzero integer is specified either in the operand or in the response to a 
WTOR message at INTRO execution time, no system interval is possible for the 
MCP. 



CPINTVL- (integer 1 
^ 1800 I 



Response Keyword: V= 

Function: Specifies the maximum number of seconds between environment 

checkpoints when the TCAM checkpoint/restart facility is used. 

Default: CPINTVL=1800 

Format: An unframed decimal integer greater than 29. 

Maximum: 65535 

Notes: See the section TCAM Checkpoint /Restart Facility of the chapter 

TCAM Service Facilities for further information on this operand. 



( 



120 OS/MFT and OS/MVT TCAM Programmer's Guide 



CPRCDS= 



( integer ^ 



Response Keyword: E= 

Function: Specifies the number of environment checkpoint records to be retained 
in the checkpoint data set at any one time. 
Default: CPRCDS=2 

Format: An unframed decimal integer greater than 1. 
Maximum: 75 

Notes: The most recent records are the ones retained. For example, if 
CPRCDS=2 is specified, the most recent two environment checkpoints are kept in 
the checkpoint data set. When a new environment checkpoint is taken, its record 
overlays the oldest environment checkpoint record then being held in the data set. 
If an attempt is made to increase or decrease integer during a warm or continua- 
tion restart, the smaller value prevails. Guidelines for coding this operand are 
included in the discussion of the TCAM checkpoint/restart facihty in the chapter 
Using TCAM Service Facilities. 




Response Keyword: S= 

Function: Specifies the type of start-up to be performed following closedown of 

the Message Control Program or system failure. 

Default: None. This operand is required. 

Format: C, CI, CY, CYI, W, WI, WY, or WYI. 

Notes: The types of restart are defined in the discussion of the TCAM 

checkpoint/restart facility in the chapter Using TCAM Service Facilities . 

The values may be specified in any order. For instance, IC is just as valid and 
produces the same results as CI. 

C specifies that a cold restart is to be performed following a normal quick close or 
flush close, and that continuation restart (including scanning of the message 
queues) is to be performed following system failure. 

CY specifies that a cold restart is to be performed following a quick close, a flush 
close, or a system failure. 

W specifies that a warm restart is to be performed following a normal quick close 
or flush close, and that a continuation restart is to be performed following system 
failure. The continuation restart will include full scanning of the message queues. 



WY specifies that a warm restart is to be performed following a quick or flush 
close, and that a continuation restart is to be performed following system failure. 
The continuation restart will not include scanning of the message queues. I 
specifies that the status of each invitation list is to be included in the checkpoint 
record. If I is not coded, invitation Usts are not checkpointed. The status infor- 
mation recorded is as follows: 

1. whether the Ust is active or inactive, 

2. whether the Ust is autopoUed or program polled. 

The specification of I prevails from one cold restart to the next. Attempts to 
change this specification during a warm or continuation restart are ignored. 



Activating and Deactivating the Message Control Program 121 



CKREQS= 



{integer "i 
5 / 



Response Keyword: R= 

Function: Specifies the maximum number of destination queues in use at any 

time for application programs that include a CKREQ macro. 

Default: CKREQS=0 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: This operand specifies the number of checkpoint request records to be set 

up in a checkpoint data set. 



If an attempt is made to increase or to decrease integer during a warm or continu- 
ation restart, the smaller value prevails. 



RESTART= 



: { integer ) 

V- ] 



Response Keyword: N= 

Function: Specifies which environment checkpoint record the TCAM restart 

facility should use in attempting to reconstruct the MCP environment as it existed 

at the time of closedown or failure. 

Default: RESTART=0 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: For more information on the use of this operand, see the section discussing 

the checkpoint/restart facility in the chapter Using TCAM Service Facilities . 



If is specified, the latest environment checkpoint record is used; if 1 is specified, 
the next to the latest record is used, etc. 



Although the maximum that may be specified is 255, the value entered must be 
less than the number of environment checkpoint records kept, as specified by the 
CPRCDS= operand. A scan is performed at restart if scanning is specified in the 
STARTUP = operand. If RESTART =0 is specified, or the operand is omitted and 
the latest environment checkpoint record cannot be used (due, perhaps, to a disk 
I/O error), TCAM automatically goes back to the latest usable record and uses it. 

If the message queues data set is on reusable disk and the integer specified causes 
TCAM to attempt to restructure the environment from a checkpoint record that 
was taken before serviced messages in certain queues were overlaid, it is unlikely 
that a warm restart or a continuation restart will be successful. 

This value should not be changed during a warm or continuation restart. 



PASSWRD= r characters \ 



Response Keyword: W= 

Function: Specifies a character string that must be entered in an MRELEASE, 

MCPCLOSE, TCHNG, or ICHNG macro issued in an application program. 

Default: PASSWRD=0 

Format: One to eight unframed characters with no embedded blanks or commas. 

Notes: If this operand is coded, none of the above macros are executed unless 

they have the correct password. A macro with an incorrect password or no 

password is ignored. PASSWRD=0 indicates that no password is being specified. 



( 



122 OS/MFT and OS/MVT TCAM Programmer's Guide 



The user will be unable to find the password as specified here in a storage dump; 
an internal TCAM routine scrambles the password at INTRO execution time. 



CROSSRF= r integer I 

I? I 



Response Keyword: F= 

Function: Specifies the number of entries in the cross-reference table. 

Default: CROSSRF=0 

Format: An unframed decimal integer. 

Maximum : 65535 

Notes: The cross-reference table is a debugging aid. Each entry contains either a 

name or an address of an internal TCAM control block associated with a line. If a 

cross-reference table is to be used, CROSSRF= should specify the maximum 

number of TCAM lines that are open simultaneously. 



This facility is described in the Debugging Aids section of the chapter Using 
TCAM Service Facilities. 



TRACE= r integer) 



Response Keyword: T= 

Function: Specifies the number of entries in the TCAM input/output trace table. 

Default: TRACE=0 

Format: An unframed decimal integer. 

Maximum : 65535 

Notes: This table provides a sequential record of the I/O interruptions occurring 

on a specified line and is described in greater detail in Debugging Aids in the 

chapter Using TCAM Service Facilities. 



TREXlT=symboI 



Response Keyword: None. 

Function: Specifies the entry point of a user- written routine to be given control 

when all entries in the TCAM I/O trace table have been used. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 



Activating and Deactivating the Message Control Program 123 



Notes: The routine is passed the address of the I/O trace table in register 0. 
Nothing is returned by the routine. There is no special restriction on what may be 
done with the table in the routine (that is, the information might be transferred to 
an external device such as the printer). The COMWRITE feature can also be 
used to provide a copy of the I/O trace table. This operand cannot be specified if 
TRACE=0. 

The entries are reusable and may be updated while the exit routine is processing 
them, since they are updated by code that is disabled to interrupts. 



DTRACE= J integer 



Response Keyword: A= 

Function: Specifies the number of entries in the TCAM dispatcher trace table. 

Default: DTRACE=0 

Format: An unframed decimal integer. 

Maxim um : 65535 

Notes: The dispatcher trace table is a debugging aid that keeps a sequential record 

of subtasks activated by the TCAM dispatcher. This table is disscussed in Using 

TCAM Service Facilities . One entry is created for each subtask activated; when 

the end of the table is reached, the table is wrapped and new entries overlay the 

oldest entries. 



OLTEST= (integer) 

112 / 



Response Keyword: 0= 

Function: Specifies the number of 1024-byte blocks of main storage to be used 

for on-line test procedures. 

Default: OLTEST=12 

Format: The unframed decimal integer 0, or an unframed decimal integer greater 

than 11. 

Maximum: 255 

Notes: For information on coding this operand, see On-Line Test Function iti the 

chapter Using TCAM Service Facilities . If the on-line test capability is not 

needed, OLTEST=0 should be coded. If the operand is omitted, 12K of main 

storage is reserved for OLT. 



/I 

1 



COMWRTE= (yes) 



Response Keyword: G= 

Function: Specifies that COMWRITE (Service Aid Writer Task) is to be at- 
tached to the TCAM MCP. 
Default: COMWRTE=NO 
Format: YES or NO. 

Notes: If COMWRTE=YES is specified, a COMWRITE DD card describing a 
sequential data set must be included in the job control cards for the execution of 
the TCAM MCP. Omission of the DD card causes abnormal termination of 
COMWRITE, and the COMWRITE function is not available. Other than the loss 
of the function, the TCAM MCP is not affected. 



( 



124 OS/MFT and OS/MVT TCAM Programmer's Guide 



WTTONE= j integer^ 

\5 J 



Response Keyword: None. 

Function: Specifies the duration of the "mark" character for the World Trade users 

whose BSC lines require a "line tone." 

Default: WTTONE=0 

Format: An unframed decimal integer. 

Maximum: 450 

Notes: Restricted to use in World Trade countries. This operand specifies the 

number of characters that constitute the tone. 



TOPlV1SG= 



^YES j 



Response Keyword: H= 

Function: Specifies whether the operator awareness message lEAOOOl is to be 

displayed at the primary operator control station when a polled station fails to 

respond to polling. 

Default: TOPMSG=YES 

Notes: The message is described in the section TCAM I/O Error-Recording 

Facilities in the chapter Using TCAM Service Facilities . 



LINETYP= / BISC 
) STSP 
\ MINI 
V BOTH 



If YES is specified, the message is displayed each time a station fails to respond to 
polling during a pass through the invitation Ust (because, for instance, the station 
is inoperative). 



Response Keyword: None. 

Function: Specifies the type of Unes used in the TCAM system. 

Default: LINETYP=BOTH 

Format: BISC, STSP, MINI, or BOTH. 

Notes: BISC is specified if all Unes in the system are BSC lines only. STSP is 

specified if all Hnes are start-stop only. MINI is specified if all lines in the system 

are IBM 1050 terminals on leased lines. BOTH is specified if all types of lines are 

supported. 



FEATURE=( (NODIALK 
i DIAL ) 



( N02741 
/2741 



(• 



JNOTIMERM 
I TIMER S 



Response Keyword: None. 

Function: Specifies additional features to be supported in the TCAM system. 

Default: FEATURE=(DIAL,2741, TIMER) 

Format: NODIAL or DIAL, N02741 or 2741, and NOTIMER or TIMER. 

Framing parentheses must be coded. If a suboperand other than the last is 

omitted due to default, a comma must be coded to indicate that it is missing. 

Notes: DIAL is specified if dial lines are used. If 2741 terminals are supported, 

2741 should be coded. The TIMER suboperand should be specified if any of the 

following features are included in the system: 



Activating and Deactivating the Message Control Program 125 



checkpoint 
any interval 
dial-out options 
main-storage queuing 
reusable disk queuing. 

If NOTIMER is specified but a function requiring the timer is used, TCAM 
terminates abnormally with a system ABEND code of 045 and a value of 06 in 
register 15. 

Note: Following the INTRO macro the user should include a section of code 
that tests the return code in register 15 to determine whether INTRO has 
executed correctly. If register 15 contains anything other than zero after 
execution of INTRO, it is unlikely that the MCP will work satisfactorily. 
(See the sample activation and deactivation section of the MCP at the end of 
this chapter for a section of user code that checks the INTRO return code 
and branches to an ABEND macro if the return code is anything other than 
zero.) 

If a nonzero code is to be returned by the INTRO routine, TCAM displays the 
message 

IED065I TCAM INITIALIZATION ERROR xxxx 

v/here xxxx is the decimal equivalent of the value returned in register 15; the 
values that may be returned are: 

Code Meaning 

4 TCAM is already in the system. 

8 There is insufficient main storage for generating one of the following: 

a. buffer-unit pool— refer to the LNUNITS= and MSUNITS= oper- 
ands. 

b. CPB free pool — refer to the CPB= operand. 

c. subtask trace table — refer to the DTK ACE = operand. 

d. line I/O trace table — refer to the TRACE= operand. 

e. cross-reference table — refer to the CROSSRF= operand. 

12 There is insufficient main storage for generating a temporary work table 

used by TCAM to sort the termname table (see the TCAM PLM for a 

discussion of the termname table). 
16 Terminal definition error. An invalid value was specified on the 

ALTDEST= operand of either the TERMINAL or the TPROCESS 

macro. 
20 The primary operator control station is invalid. Either no such terminal 

entry exists, or SECTERM=YES is not specified for the terminal named 

on the PRIMARY = operand of the INTRO macro. 



{ 



1 26 OS/MFT and OS/MVT TCAM Programmer's Guide 



I 



OPEN 



The OPEN macro 

• completes initialization and activation of data sets belonging to the Message 
Control Program; 

• is required for each MCP data set represented by a DCB macro; and for log 
data sets (if present), 

• specifies whether activation of lines represented by line group data sets is to be 
immediate or deferred. 

OPEN is used to complete initialization and activation of MCP data sets, and to 
provide an interface with the BSAM routines handling the logging function for 
TCAM. Each MCP data set required for execution (with the exception of a 
message queues data set in main storage) must be activated in the Message 
Control Program by an OPEN macro. Log data sets, if present, are also activated 
by an OPEN macro issued in the MCP. Each MCP data set may be activated by a 
separate OPEN macro, or all data sets of the same type (for example, all line 
group data sets, or all message queues data sets) may be activated as a group by a 
single OPEN. If message queues data sets residing on disk are present, they must 
be opened first. The checkpoint data set, if present, must be opened next. 

Instead of a standard OPEN macro, the user may code a list and an execute form 
of the macro, which would be used in conjunction with each other; for general 
information on the Ust and the execute form of a macro, including a discussion of 
the advantages of using these forms, see the OS publication Supervisor Services . 

When an OPEN macro tries and fails to properly open a TCAM data set, an error 
message is sent to the system console. This error message, which specifies the 
data set that could not be satisfactorily opened and tells why it could not be 
opened, is described in the section User ABEND Exits of the chapter Defining 
the MCP Data Sets . In addition to sending the error message, TCAM allows the 
us.er to specify a user-written subroutine that receives control when an OPEN 
macro fails to execute properly. This capabiUty is described in the User ABEND 
Exits section. If the user fails to provide this subroutine, TCAM issues an 
ABEND macro for the MCP program when an OPEN fails to execute properly. 

When an OPEN macro is executed for a Hne group data set, TCAM issues com- 
mands to prepare each line for message traffic. If TCAM does not receive an 
indication that the commands have successfully executed within 28 seconds from 
the time they were issued, the line is considered to be temporarily unavailable, and 
the following message is written at the system console: 

IED079I ENDING STATUS NOT RECEIVED FROM 
LINE nnn — LINE UNAVAILABLE 

The unavailable line may subsequently be started by the STARTLINE operator 
command. Unavailability of one Une does not affect preparation for message 
traffic over other lines in the line group. 

The operand field of the OPEN macro consists of one or more groups of position- 
al operands, followed by a single keyword operand. Each group of positional 
operands consists of the name of the data control block for the data set being 
opened (the name of the block is the same as the name of the DCB macro that 
created it) and some optional information about that data set. A comma is coded 



Activating and Deactivating the Message Control Program 1 27 



between groups. The optional keyword operand at the end permits the list and the 
execute form of the macro to be specified. 



OPEN has the following format: 



Name 


Operation 


Operands 


[symbol] 


OPEN 


(dcbname,[((OUTPUT)[,IDLE])],...) 
{ INOUT > 
1 INPUT ) 

Umf=l n 

\MF=(E,listname) j 



symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: If MF=L is specified, this macro name must also be provided. It becomes 

the name of the parameter list generated by the macro. 



dcbname 



Function: Specifies the name of a data control block identical with the name 

specified in the symbol field of the DCB macro for the data set being opened. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: Register notation may also be used, in which case the specified register (2 

through 12) should contain the address of the data control block for the data set 

being opened. 



,4 



> OUTPUT I 
' INOUT 
I INPUT ' 



Function: Specifies the type of data set with respect to the direction in which 

message traffic may flow. 

Default: INPUT 

Format: OUTPUT, INOUT, or INPUT. 

Notes: OUTPUT specifies an output data set; it must be specified for a log data 

set. The operand may be coded for a line group data set if none of the lines are to 

stations that can enter data; in this case, the INVLIST= operand of the Hne group 

DCB macro must refer to an invitation list having no entries (see the description 

of the INVLIST macro). 

INOUT specifies a data set that can be used for both input and output. INOUT 
must be specified for a DASD message queues data set or a checkpoint data set, 
and should be specified for a line group data set if any of the lines are to stations 
that both enter and accept data. INPUT specifies an input data set. This operand 
may be specified if none of the lines are to stations that can accept data. 



( 



1 28 OS/MFT and OS/M VT TCAM Programmer's Guide 



IDLE 



IMF 



=^L 
<(E,H 



Hstname) 



> 



Function: Specifies whether the lines are to be activated when OPEN is executed. 
Default: None. Specification optional. 
Format: IDLE 

Notes: This operand is meaningful only for a line group data set. If IDLE is 
coded, the line group data set is initialized at OPEN execution time, but the lines 
are not activated. That is, no invitation or selection is performed for stations on 
this line. Such Unes may be activated individually by a STARTLINE operator 
command. If IDLE is omitted, all lines in the line group are automatically activat- 
ed when the OPEN macro is executed. For nonswitched lines to stations having 
polling characters, poUing of stations having active entries in the invitation lists for 
the lines begins after OPEN is executed, provided that INPUT or INOUT is also 
specified. 

A station assigned to a switched Une that is idle may not call in on that hne, but 
may call in on any active Une in its line group to enter messages. Such a station 
will not receive any messages queued for it until the line it is on is activated by the 
STARTLINE operator command. 

If neither INOUT, INPUT, OUTPUT, nor IDLE is specified for a particular data 
set, and a subsequent data control block address is specified in the sublist, two 
commas must appear between the two specified data control block names. 



Function: Specifies whether the OPEN macro is to generate a parameter Ust only 
or is to generate executable code. 
Default: None. Specification optional. 

Format: Hstname specifies the name of an OPEN macro specifying MF=L. 
Notes: MF=L causes creation of a parameter list based on the OPEN operands. 
No executable code is generated. The user must specify this form of the OPEN 
among his program constants. The parameters in the Ust are not used until the 
program issues an OPEN or CLOSE macro with an MF=(E,Ustname) operand 
that refers to the Ust. The name specified in the name field of the OPEN macro 
becomes the name assigned to the parameter Ust. MF=(E,listname) causes 
execution of the OPEN routine using the macro having the MF=L operand 
specified. Parameters specified through a macro having MF=(E,Ustname) operand 
override corresponding parameters in the list. 

Example: 

The following OPEN macros open: 

L Two DASD message queues data sets named (as assigned by their DCB mac- 
ros) DISKREUS and DISKNON; 

2. A checkpoint data set named TPCHK; 

3. A line group data set named GROUPONE, and another line group data set 
named GROUPTWO that is to be opened idle; 

4. A log data set named MSGLOG. 

OPENDISK OPEN ( DISKREUS , ( INOUT ) , DISKNON , ( INOUT ) ) 

OPENCKPT OPEN ( TPCHK, ( INOUT ) ) 

OPENLINE OPEN ( GROUPONE , ( INOUT ) , GROUPTWO , ( INOUT , IDLE ) ) 

OPENLOG OPEN ( MSGLOG , ( OUTPUT ) ) 

Note that the message queues data sets are opened first and that the checkpoint 
data set is opened next. 



Activating and Deactivating the Message Control Program 129 



READY 



The READY macro 

• completes initialization and activation of the MCP; 

• permits ''Good Morning" and "Restart in Progress" messages to be specified; 

• must be issued between the OPEN macros and the CLOSE macros in the 
activation and deactivation section of the MCP. 

The READY macro completes initialization and activation of the Message Control 
Program; once READY has executed, the TCAM system is prepared for message 
traffic. One READY macro is specified per MCP, and is located between the 
OPEN macros and the CLOSE macros in the activation and deactivation section 
of the MCP. 

Two optional operands of READY provide the addresses of user-written routines 
that may build "Good Morning" or "Restart in Progress" messages or that might 
alter option fields and other control areas to reflect the fact that a restart has 
occurred. The exit for the "Good Morning" message is taken for the initial 
start-up of the MCP and for each cold restart; the exit for the "Restart in 
Progress" message is taken for a warm or a continuation restart (for a discussion 
of the various types of TCAM start-up, see TCAM Checkpoint /Restart Facility 
in Using TCAM Service Facilities ). 

When initial start-up or a restart occurs, the appropriate routine is given control 
for each station defined by a TERMINAL macro, provided that the line group 
data set containing the line on which the station is located has been opened by an 
OPEN macro. The user routine should save and restore registers. When control 
passes to the user routine, register 1 contains the address of a two-word parameter 
list. The first word in the Ust contains the address of the terminal table entry for 
the station to which the message generated by the user is to be sent; the second 
word contains the address of the option fields for the destination station. The user 
routine may use this information to build a message tailored to this particular 
station, and may also alter fields in the terminal table entry and the option fields 
for the station to reflect the fact that a restart has occurred (for a warm start or 
continuation restart, the data in the terminal table entries and the contents of the 
option fields before closedown or failure are preserved by the checkpoint faciUty). 

The user routine returns to the MCP, in register 15, the address of a message to be 
sent to the station. An all-zero address indicates that no message is to be sent to 
this station. At the specified address is a one-byte field indicating, in binary form, 
one more than the number of bytes of data in the message, followed by the text of 
the message. The maximum length of the message is 255 bytes. If queuing is by 
terminal, TCAM places the message at the head of the queue for the destination 
station so that it is the first message sent to that station following start-up or 
restart. The message is handled by the outgoing group of the Message Handler for 
the destination, and is transmitted like any other message. Since the message is 
handled by an MH group, it must have a header similar in format to the headers of 
messages usually handled by the group. The user must construct this header in his 
exit routine and include it as the first part of his message. 

If queuing is by line, the good morning or restart messages for the stations on a 
line will be placed at the head of the destination queue for that Hne, and will be 
sent before any other messages on that queue. 



( 



130 OS/MFT and OS/MVT TCAM Programmer's Guide 



READY has the following format: 



symbol 



GMIVISG=routine 



RSIVlSG=routiiie 



Deactivation 



Name 


Operation 


Operands 


[symbol] 


READY 


[GMMSG=routine][,RSMSG=routine] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of a user- written, closed subroutine that builds 

good morning messages on each line. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is coded, the routine is given control at the initial start-up 

and at each cold restart. 



Function: Specifies the name of a user- writ ten, closed subroutine that builds 

restart messages. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is coded, the routine is given control at a warm restart or a 

continuation restart. 

The routines are coded and assembled as part of the MCP in the same manner as 
the Message Handlers. Their exact location is not important since they are called 
as closed subroutines. See User Code in a Message Handler in the chapter 
Designing the Message Handler for the correct linkages. 



Orderly deactivation of the TCAM system involves a number of steps. Incoming 
and outgoing message traffic must be stopped, and if the status of the system is to 
be preserved, a checkpoint record must be made. Data sets for any application 
program using TCAM be closed. Finally, the MCP data sets must be closed and 
control returned to the OS Supervisor. 



Types of Closedown 



Closedown of a TCAM system may be initiated either by a SYSCLOSE operator 
command or by an MCPCLOSE macro issued in an application program. These 
two means of initiating closedown are described in the next two sections. Both 
the operator command and the macro have an operand that specifies whether a 
flush closedown or a quick closedown is to be effected. A flush closedown may 
also be initiated internally when the nonreusable disk threshold is reached. 

A flush closedown is one in which incoming message traffic on each line ceases 
after the message being received at the time closedown is ordered has been 
completed (the line is not repoUed or re-enabled). As soon as incoming message 
traffic on each line ceases, any eligible outgoing messages that have been queued 
for stations on that line are sent. (An eligible message is a message to a station or 
application program that is not intercepted; see the description of the HOLD 



Activating and Deactivating the Message Control Program 131 



macro.) In this manner, incoming message traffic declines to nothing, while 
outgoing message traffic continues until all ehgible messages have been sent. An 
environment checkpoint record is taken after all eligible outgoing messages have 
been sent. This record preserves the status of the MCP and also records the 
locations on disk of outgoing messages that could not be sent because their 
destinations were intercepted; after restart, these messages are sent once their 
destinations are eligible to receive them. This form of termination is known as a 
flush closedown because unsent messages are flushed from the message queues. 

When a quick closedown is ordered, message traffic stops on each line as soon as 
transmission of any message currently being sent or received on the line has been 
completed. Queues of messages to be sent are not flushed but their status is 
preserved by an environment checkpoint record, and they are sent to their appro- 
priate destinations after restart. (See the discussion of the TCAM 
checkpoint/restart facility in the chapter Using TCAM Service Facilities .) 

Deactivating a TCAM System without Application Programs 

If there are no appUcation programs in the TCAM system, a SYSCLOSE operator 
command entered at an operator control station deactivates the system. The 
SYSCLOSE command is discussed in the operator control section of the chapter 
Using TCAM Service Facilities. 

The SYSCLOSE command specifies either a quick or a flush closedown. When 
the command is executed, traffic is suspended on each Hne, as described above. 

When all message traffic and TCAM disk operations are complete, control returns 
to the first instruction following the READY macro in the Message Control 
Program. This instruction must begin a user-written routine (or branch to a 
routine) that deactivates the Message Control Program. This MCP deactivation 
routine must issue CLOSE macro instructions for each open data set in the 
Message Control Program. 

The last TCAM data sets to be closed must be the checkpoint and then the DASD 
message queues data sets. This is important, because closing these data sets 
deactivates the telecommunications system. After the message queues data sets 
have been closed, no further references can be made to queues, control blocks, the 
terminal table, invitation lists, etc. The deactivation routine should end with a 
RETURN macro to end the message control job. (For a sample MCP deactiva- 
tion routine, see the last section of this chapter.) 

Deactivating a TCAM System With Application Programs 

When the TCAM system includes apphcation programs, closedown may be 
effected by an MCPCLOSE macro issued as part of a termination routine in an 
application program. A recommended procedure is to enter a special closedown 
message at a station; this message would be directed to each active application 
program in the system (by specifying the names of the appropriate process entries 
in the terminal table as destinations). Each application program might contain a 
user-written termination routine that would be activated when the message was 
received. The termination routine might perform the following steps: 

1. Close any open application-program data sets; 

2. Issue an MCPCLOSE macro; 

3. Issue a system RETURN macro in order to end the apphcation program job. 

The user may code the SETEOF macro to execute on his closedown message. 
When the application program receives the message on which SETEOF has 



1 32 OS/MFT and OS/MVT TCAM Programmer's Guide 



< 



executed, it branches to the address specified by the EODAD= operand of the 
input DCB macro when the next GET or CHECK macro is issued; at this address 
the user may have his closedown routine. 

When multiple application programs are being closed, an MCPCLOSE macro may 
be issued in each; the MCPCLOSE macro issued first is the only one to execute. 

The MCPCLOSE macro checks to see whether an MCPCLOSE macro has 
already been issued; if so, the macro does not execute, but places a return code of 
X'OO' in register 15. The first MCPCLOSE macro issued causes all message 
traffic on TCAM lines to cease, as described above in the discussion of the types 
of closedown. An operand of MCPCLOSE specifies either a quick or a flush 
closedown. After all message traffic has ceased, the Message Control Program 
checks for open application-program data sets; when all such data sets are closed, 
control passes to the instruction following the READY macro in the MCP. This 
instruction begins a user-written routine (or branches to a routine) that issues 
CLOSE macros for each data set opened in the MCP and ends with a system 
RETURN macro. A sample routine is given in the last section of this chapter. 

Instead of using an MCPCLOSE macro, the user may utilize the SYSCLOSE 
operator command to close a TCAM system having application programs. If any 
application program data sets are open at the time message traffic ceases, an error 
message is directed to the system console; the error message lists the open data 
sets for that application program. If more than one application program has open 
data sets, the message for the second application program will not be sent to the 
console until all data sets for the first program are closed. When these data sets 
are closed, the system is deactivated. 

i^ SYSCLOSE and MCPCLOSE will also allow the user to close all open application 

program DCBs by forcing the GET/READ routine to take the EODAD exit for 
each open input DCB. This is done only if the user codes the STOP= operand 
and the EODAD= operand on the input DCB. The error message is still issued 
because the user EODAD= operand may not point to a closed routine. 

Note: When issuing the READ macro without issuing the CHECK macro, 
at least one message must be read before the EODAD exit is taken. 



i 



Activating and Deactivating the Message Control Program 133 



CLOSE 



symbol 



(dcbname,,...) 



The CLOSE macro 

• is issued in the Message Control Program to deactivate any log data set, line 
group data set, checkpoint data set, and DASD message queues data set that is 
open in the MCP; 

• must appear following the READY macro or be branched to from instructions 
following READY. 

CLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CLOSE 


(dcbname,,...) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the names of the data control blocks for the data sets being 
closed. 

Default: None. This operand is required. 

Format: Each dcbname must conform to the rules for assembler language sym- 
bols and must correspond to the name specified on the DCB macro for the data 
set being closed. 

Notes: Register notation may be used, in which case the addresses of the data 
control blocks must previously have been loaded into the general registers speci- 
fied. 

All MCP data sets of the same type (for example, all hne group data sets or all 
message queues data sets) can be closed with one CLOSE macro by including the 
names of their data control blocks as operands. If more than one dcbname is 
coded in a CLOSE macro, the names are separated by double commas. 

If present, the last TCAM data sets to be closed must be the checkpoint and then 
the DASD message queues data sets. 

Sample MCP Activation and Deactivation Section 

The code in Figure 8 represents an activation and deactivation section as it might 
appear in an MCP. The section consists of an INTRO macro, some user code that 
tests whether INTRO worked correctly and causes termination of the MCP if 
INTRO did not execute properly, OPEN macros, a READY macro, and CLOSE 
macros. The TCAM macros in this section should appear in the order shown. 



Since the CPB= operand of the INTRO macro is omitted (and DISK=YES is 
coded), the TCAM system will issue a WTOR message at INTRO execution time; 
in his response to this message, the user may specify a value for CPB= and 
override or supply values for many other INTRO operands. 



( 



1 34 OS/MFT and OS/MVT TCAM Programmer's Guide 



TCAMINIT INTRO PROGID=MCPONE , 
DISK=YES, 
CONTROL=OPID, 
KEYLEN=48, 
LNUNITS=20, 
DLQ=NYC, 
USEREG=10, 
CPINTVL=1000, 
STARTUP=W, 
CKREQS=2, 
PASSWRD=VALIDMSG , 
CROSSRF=10 
OLTEST=10 

LTR 15,15 

BZ OPENDISK 



4c 

NOEXEC 
* 

OPEN DISK 



ABEND 12 3, DUMP 

OPEN (DISKREUS,( INOUT ) , DISKNON, ( INOUT ) 
TM DISKREUS+48, 16 
BNO NOEXEC 



PROGRAM IDENTIFICATION 

USING DISK 

FOR OPERATOR COMMANDS 

UNIT LENGTH 

NUMBER OF UNITS 

DEAD-LETTER QUEUE 

REGISTERS TO BE SAVED 

CHECKPOINT INTERVAL 

WARM RESTART 

CHECKPOINT REQUESTS 

PASSWORD FOR APPLICATIONS 

CROSS-REFERENCE ENTRIES 

ON-LINE TESTS 

TEST IF INTRO WORKED 

IF SO OPEN DATA SETS 

IF NOT TERMINATE WITH DUMP 

OPEN DISK DATA SETS 
TEST IF OPENS WORKED 
NO-TERMINATE 



* 
* 
* 
* 

* 

* 
* 

* 



TM DISKNON-f48, 16 
BNO NOEXEC 



CPENCKPT OPEN ( TPCHK, ( INOUT ) ) 
TM TPCHK4-48,16 
BNO NOEXEC 



OPEN CHECKPOINT DATA SET 



OPENLINE OPEN ( GROUPONE , ( INOUT 

TM GROUPONE+48, 16 

BNO NOEXEC 

* 

TM GROUPTWO+48, 16 

BNO NOEXEC 



I , GROUPTWO , ( INOUT , IDLE ] 



OPEN LINES 



OPENLOG OPEN ( MSGLOG , ( OUTPUT : 

TM MSGLOG+48,16 
BNO NOEXEC 



OPEN MESSAGE LOGGING DATA 
SET 



ALLSWELL READY GMMSG=RTNA, RSMSG=RTNB 
* 

FINISHUP CLOSE ( GROUPONE ,, GROUPTWO ) 

CLOSE (MSGLOG) 

CLOSE (TPCHK) 

CLOSE ( DISKREUS , , DISKNON ) 

L 13,4(13) 
RETURN ( 1 4 , 1 2 ) , , T 



Figure 8. Sample MCP Activation and Deactivation Section 



BEGIN EXECUTION 

CLOSE LINE GROUP DATA SETS 

CLOSE LOG DATA SET 

CLOSE CHECKPOINT DATA SET 

CLOSE DISK DATA SETS 

PREPARE TO RETURN 

RETURN CONTROL TO OS 

SUPERVISOR 



The section of user code following the INTRO macro is optional, but the user 
should test the return code in register 15 to determine whether INTRO has 
executed correctly. If register 15 contains anything other than zero after execu- 
tion of INTRO, the chances are that the MCP will not work properly. 



I 



The OPEN macro in Figure 8 is the same as that used as an example in the 
previous section. The DASD message queues data sets are opened first, and the 
checkpoint data set is opened next. (Neither of these data sets is required, but if 
present they should be opened in the order shown.) 



Activating and Deactivating the Message Control Program 1 35 



A user-written subroutine may be utilized to perform error checking and correc- 
tion when a TCAM data set fails to open. The EXLST= operand of the DCB 
macro for the data set may be coded so that control passes to the user's subroutine 
whenever the data set fails to open. (For more information on the EXLST= 
operand, see the descriptions of the DCB macros for the various TCAM data 
sets.) In this example, the flags set by the OPEN macro are tested for successful 
completion. Open flags are at an offset of 48 beyond each DCB macro and are set 
to 16 if the data set is opened correctly. If the open flags are not equal to 16, the 
abnormal exit is taken. 

The READY macro is the last macro of the activation section. RTNA is the name 
of a user-written, closed subroutine that will be activated for the initial start-up 
and each cold restart; RTNB is given control for warm and continuation restarts. 
Both routines are entered once for each station represented by an entry in the 
terminal table and located on a line whose Une group data set has been opened. 

The first CLOSE macro begins the deactivation section. This CLOSE will not be 
executed until all data sets in TCAM application programs have been closed down 
and until all lines have been closed to traffic by means of a SYSCLOSE operator 
command or an MCPCLOSE macro issued in an application program. The first 
CLOSE is given control by TCAM once Hne traffic has ceased. Notice that the 
DASD message queues data set is closed last, immediately after the checkpoint 
data set; this practice should be followed when these two data sets are present. 

The instructions following CLOSE return control to the OS Supervisor. 



i 



< 



136 OS/MFT and OS/MVT TCAM Programmer's Guide 



Message Format 



Designing the Message Handler 



The heart of a Message Control Program consists of the Message Handlers , the 
sets of routines that operate upon messages being received from or sent to remote 
stations or appUcation programs. A Message Handler is defined by a sequence of 
TCAM macro instructions and is constructed to handle messages for a particular 
line group or for several line groups that have similar characteristics. 

A Message Handler (MH) defines macro-introduced routines that: 

1. Examine and process control information in message headers; 

2. Perform necessary functions in preparing message segments for forwarding to 
theirdestinations, which may be stations or application programs. 

There are two kinds of macro instructions that may be included in a Message 
Handler: functional and delimiter macro instructions. The functional macros 
perform the specific operations required for messages directed to the Message 
Handler. Delimiter macros classify and identify sequences of functional macro 
instructions and direct control to the appropriate sequence (some delimiter macros 
have limited functional capabilities). 

Designing a Message Handler consists of selecting certain TCAM macro instruc- 
tions described in this chapter and writing them in a particular sequence, accord- 
ing to the requirements of the application and the characteristics of the hnes. It is 
important to consider the type of station and the type of line in use, the processing 
requirements of different types of messages, and the format of the message 
headers to be handled. 

Before discussing the Message Handler and its parts, we shall briefly consider the 
format of the TCAM message and its message header. 



A message may consist of two parts, the header and text. The header contains 
control information for the message, such as: 

• one or more destination codes, 

• the code name for the originating station, 

• the number of the message relative to previous messages received from that 
station(input sequence number), 

• a message-type indicator, 

• various other fields containing control indicators. 

The text of a message consists of information of concern to the party ultimately 
receiving the message, either a station or an application program. 

Depending on the application, messages may consist of a header only, text only, or 
header and text. A header-only message may utilize a message-type indicator to 
route the message to an application program and, possibly, obtain a standard 
response. If all messages go to only one application program, such as a file-update 
program, the header may be omitted. 

The determination of what part of the message is the header and what part is text 
is up to the user. 

Depending on the type of work unit with which he is deaUng, the user must specify 
appropriate characters for control purposes. The types of work units are: 



Designing the Message Handler 1 37 



• A block is that portion of a message terminated by an EOB or ETB control 
character, or, if this is the last block in the message, by an ETX or EOT control 
character. A subblock is that portion of a BSC message terminated by an ITB. 

• A segment is that portion of a message contained in a single buffer. The size of 
the buffer is specified by the user for each line group and appUcation program. 

• A record for an application program is, most often, that portion of a message 
terminated by a format character (ESC, NL, TAB, CR, or LP), or a message 
portion terminated by a character specified by the data operand of the 
MSGEDIT macro (see the description of this macro). 

• A physical message is a unit of data terminated by an EOT or ETX control 
character, or, if the CONV= operand of the STARTMH macro is coded 
CONV= YES, by an ETB or EOB control character (see the description of the 
STARTMH macro). 

• A logical message is a unit of data defined by the user (see the description of 
the SETEOM functional macro). If the user does not define logical messages 
for his network, TCAM assumes that a logical message is equivalent to a 
physical message. 



The Message Header 



Operating on the fields of the message header is the primary function of Message 
Handlers in the Message Control Program. The length and format of the header 
and the information it contains depend solely on the requirements of the appUca- 
tion and the user's preferences. The length may be a few characters or many 
characters. A header may occupy more than one buffer. However, the entire 
header of a message must be contained within the first block of the message. 
EOBs may not be embedded within a header. 



The format of the message header dictates the arrangement of the appropriate 
Message Handler macros. The control characters used and the sequence of fields 
within the header must be predetermined so that the Message Control Program 
can be properly coded. 

Destination codes in the message header identify the stations or application 
programs to which the message is to be routed. The message-type indicator can 
identify a header that is to be processed in a special manner. By coding certain 
macro instructions, the user can insert in the header such data as the date and time 
it is sent, and the output sequence number. 

There are many possible variations for the format of a message header. The 
sample formats shown in Figures 9 and 10 are included simply for illustrative 
purposes. 

The format shown in Figure 9 could be used in a message switching appUcation. 
This figure shows how an incoming message might look just before it comes into 
main storage. 

In this example, the EBCDIC blank character (here denoted by the symbol b) 
serves as a delimiter for each header field. This is not always the case, however; 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 17 


18 


19 




# 


1 


9 


2 


K 


C 


H 


1 


K 


N 


Y 


C 


K' 


P 


H 


1 


K 


/ 


)i 


1 


Text ( 



< 



Figure 9. Sample Format for an Incoming Message 



1 38 OS/MFT and OS/MVT TCAM Programmer's Guide 



some MH macros operating on the header do not look for field delimiters, but 
consider a certain number of characters or a certain sequence of characters to be a 
header field. To determine what constitutes a header field for any particular 
macro, the user should consult the description of that macro in the section 
Functional Macro Instructions . 

Byte contains a machine end-of-address (EOA) character inserted by the 
station. When the message is transmitted, this character signals the end of ma- 
chine control characters (such as addressing characters and the machine EOA 
itself, which are not recorded) and the beginning of data characters. Depending 
upon how the LC= operand of the STARTMH macro of the Message Handler is 
coded, TCAM may remove the machine-control characters and the machine EOA 
before placing the message in main storage. The 192 in bytes 1 through 3 is the 
input sequence number. Bytes 5 through 7 contain the code for the terminal that 
originated the message. Bytes 9 through 11 and 13 through 15 contain destination 
codes specifying the stations to which the message is to be sent. In this example, 
the semicolon in byte 17 has been designated by the user as the program EOA 
character. Since some of the messages in this application contain multiple destina- 
tion codes, the destination delimiter character must follow the last destination 
code (for more on the program EOA character, see the description of the 
FORWARD macro). Byte 19 contains a character specifying the priority of the 
message. The remaining portion of the message is text and is followed by the 
EOT character (which must be inserted by the station operator to indicate the end 
of the message). 

If LC=OUT is coded in the STARTMH macro, all control characters (including 
the machine EOA) are deleted after the message is placed in buffers; the buffers 
must be large enough to accommodate these characters. If the user wishes to 
insert time-received, date-received, and output-sequence information into his 
message header, he must code the RESERVE= operand of the line group DCB 
macro to specify the number of bytes to be reserved in his input buffer. (The user 
may also insert data into his message by the MSGEDIT macro; no buffer space 
need by reserved for data inserted by MSGEDIT.) 

Figure 10 shows how the message would look when transmitted to a destination 
station. In this example, the Message Control Program inserted time-received and 
date-received information in the header. The time-received information in bytes 
26 through 33 indicates that the message was received at 1 1 hours, 30 minutes, 
and 45 seconds on the date specified in bytes 19 through 24, which is November 
5, 1969. Insertion of this information moved the priority data to byte 35. The 
message is then queued by priority on the message queue for the destination 
station. When the message reentered main storage before transmission to the 
destination stations, the Message Control Program placed a blank followed by the 
output sequence number in bytes 36 through 40 of the header. TCAM sends a 
series of control characters (ending with the machine EOA) before sending the 
message to its destination; TCAM supplies an EOT character when the 
MSGFORM macro is coded. 



Designing the Message Handler 1 39 



Byte: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 18 


19 


20 


21 22 


23 


24 25 


# 


I 


9 


2 


K 


c 


H 


1 


K 


N 


Y 


C 


K 


P 


H 


1 


K 


/ 


¥ 


6 


9 


• 


3 





9 


K 



26 27 28 


29 


30 


31 


32 


33 


34 35 


36 37 38 39 40 




1 


1 


• 


3 





• 


4 


5 


^ 


1 


K 





8 


3 


1 


Text 



E 
O 
T 



Figure 10. Sample Format for an Outgoing Message 

A Message Handler is divided into two main groups of macro instructions, the 
incoming group and the outgoing group. The incoming group handles all messages 
that arrive at the Message Control Program; these messages may originate from 
any of the lines, line groups, or application programs that are assigned to have 
their messages operated on by the Message Handler. The outgoing group handles 
messages being sent from the Message Control Program to any of the lines, line 
groups, or application programs. 

Each of the two groups of a Message Handler may be divided into subgroups. The 
incoming group may have the following subgroups: 

• inblock subgroups, which process all incoming message segments; 

• inheader subgroups, which handle only those incoming message segments that 
include all or part of a message header; 

• inbuffer subgroups, which process all incoming message segments; and 

• inmessage subgroups, which are executed after a complete message has arrived 
at the CPU. 

The outgoing group has three possible subgroups: 

• outheader subgroups, which handle only those outgoing message segments that 
include all or part of a message header; 

• outbuffer subgroups, which process all outgoing message segments, and 

• outmessage subgroups, which are executed after a complete message has been 
sent. 

Functions Performed by MH Subgroups 

The following presents an overview of MH organization and describes typical 
functions performed in each type of subgroup. The words in parentheses are the 
names of the MH macros that perform the functions described. 



Macro or Subgroup 



STARTMH 



Function 

Determines whether this is an incoming or an outgoing 
message, and routes it to the appropriate MH group. 



Inblock Subgroup 



Operates on each incoming segment: 

• Determines whether the message should be translat- 
ed to EBCDIC (CODE) 

• Counts incoming messages or message segments 
(COUNTER) 



< 



1 40 OS/MFT and OS/M VT TCAM Programmer's Guide 



Inheader Subgroup 



Inbuffer Subgroup 



Inmessage Subgroup 



Outheader Subgroup 



> 



Edits header fields and text across buffer bounda- 
ries (MSGEDIT, MSGFORM) 
Constructs logical messages 



Operates on an incoming message header: 

• Determines whether the message should be translat- 
ed to EBCDIC (CODE) 

• Determines the message origin and destination 
(ORIGIN, FORWARD) 

• Checks the incoming sequence number 
(SEQUENCE) 

• Determines the message priority 
(PRIORITY) 

. Edits header fields (MSGEDIT) 

• Moves data to be broadcast into a common data 
area and schedules a broadcast operation 
(COMMBUF) 



Operates on each segment of an incoming message: 

• Counts incoming message segments 
(COUNTER) 

• Edits text (MSGEDIT) 

• Checks the length of incoming messages and 
terminates reception for messages that are too long 
(CUTOFF) 

• Moves data to be broadcast into a common data 
area and schedules a broadcast operation 
(COMMBUF) 



Specifies actions to be taken after the entire message 
has been received: 

• Logs the message (LOG) 

• Cancels the message or the last block of the mes- 
sage (CANCELMG) 

• Returns error messages to the originating station 
(ERRORMSG, MSGGEN) 

• Retries to contact a switched station (RETRY) 



Operates on an outgoing message header: 

• Inserts the date and time into the outgoing header 
(DATETIME) 

• Assigns an outgoing sequence number to the 
message and inserting it in the header 
(SEQUENCE) 

. Edits header fields (MSGEDIT) 

• Determines whether the message should be translat- 
ed to line code (CODE) 



Designing the Message Handler 141 



Outbuffer Subgroup 



Determines whether line-control characters should 

be inserted into the outgoing message 

(MSGFORM) I 



Operates on each segment of an outgoing message: 

• Counts outgoing message segments 
(COUNTER) 

. Edits text (MSGEDIT) 

Outmessage Subgroup 

Specifies actions to be taken after the entire message 
has been sent: 

• Logs the messrage (LOG) 

• Sends an error message to the destination station 
(ERRORMSG, MSGGEN) 

• Intercepts messages to the destination station 
(because, perhaps, the station is inoperative) 
(HOLD) 

More than one subgroup of a particular kind may be included within a group to 
accommodate variations in handling that may be required by various kinds of 
messages (see Variable Processing within a Message Handler in this chapter). 

Delimiter macros identify the beginning and end of different MH groups and 
subgroups. The STARTMH macro identifies the beginning of an MH. 
INBLOCK, INHDR, INBUF, and INMSG respectively identify the beginning of | 

the inblock, inheader, inbuffer, and inmessage subgroups of the incoming group. \i 

INEND identifies the end of the incoming group. OUTHDR, OUTBUF, and 
OUTMSG respectively identify the beginnings of the outheader, outbuffer, and 
outmessage subgroups of the outgoing group, while OUTEND identifies the end 
of this group. The delimiter macros are discussed in detail later in this chapter. 

A minimum Message Handler consists of a STARTMH macro and either an 
incoming group or an outgoing group (either group may be omitted, as when the 
incoming group is omitted for an output-only line). If the outgoing group is 
omitted, the OUTEND macro must be coded to preserve addressabihty. The 
incoming group must precede the outgoing group if both are included in an MH. 

The following rules govern the arrangement of subgroups within a group: 

L If there is an incoming group not handling logical messages or editing data 
across buffer boundaries, an inheader subgroup is required as the first sub- 
group. If logical messages are being handled by this incoming subgroup, or if 
data is to be edited across buffer boundaries (MSGEDIT,MSGFORM), an 
inblock subgroup must precede the inheader subgroup. An inblock subgroup 
may be followed by another inblock subgroup or an inheader subgroup. All 
other subgroups of the incoming groups are optional. 

2. The first inheader subgroup in an incoming group may be followed by any 
combination of inheader and inbuffer subgroups. 

3. Inmessage subgroups, if present, must be the last subgroups in the incoming 
group. 

4. Any of the three types of subgroups for the outgoing group may appear as the 
first subgroup in the group. However, if an outmessage subgroup is the first 
subgroup, no outheader or outbuffer subgroup may appear in the group. 



( 



1 42 OS/MFT and OS/MVT TCAM Programmer's Guide 



5. Outheader and outbuffer subgroups may appear in the outgoing group in any 
order (that is, either subgroup may appear first and each may be specified more 
than once). 

6. Outmessage subgroups, if present, must be the last subgroups in the outgoing 
group. 

The sample Message Handlers in this chapter illustrate some of the ways in which 
subgroups may be arranged. 

The presence or absence of particular groups and subgroups within a given 
Message Handler depends upon the requirements of the user. Figure 1 1 summa- 
rizes the MH macros that may appear within a given subgroup. The user should 
familiarize himself with the functions of the macros shown in Figure 1 1 and decide 
which of these functions to incorporate into his Message Handler. His choice of 
functions will determine which subgroups will be present in his MH. For example, 
if he decides he needs the function provided by the CANCELMG macro in his 
MH, then he will require an inmessage subgroup. Some macros (CODE, 
COUNTER, LOG, for example) may appear in more than one kind of subgroup, 
but their functions vary according to the kind of subgroup in which they appear. 



Designing the Message Handler 1 43 





CODE 


MSGFORM 




COUNTER 


MSGLIMIT 




LOG 


PATH 


Inblock 


LOCOPT 


SETEOM 


Subgroup 


MSGEDIT 


TERRSET 




CHECKPT 


MSGEDIT 




CODE 


MSGLIMIT 




COMMBUF 


MSGTYPE 




COUNTER 


ORIGIN 


Inheader 


DATETIME 


PATH 


Subgroup 


FORWARD 


PRIORITY 




HOLD 


QACTION 




INITIATE 


SEQUENCE 




LOCK 


SETSCAN 




LOCOPT 


TERRSET 




LOG 


TGOTO 




MHGET 


TYPETABL 




MHPUT 


UNLOCK 




CHECKPT 


MHGET 




CODE 


MHPUT 




COMMBUF 


MSGEDIT 




COUNTER 


PATH 


Inbuffer 


CUTOFF 


TERRSET 


Subgroup 


LOCOPT 
LOG 


TGOTO 




CANCELMG 


MSGGEN 




CHECKPT 


REDIRECT 


Inmessage 


ERRORMSG 


RETRY 


Subgroup 


HOLD 
LOG 


SLOWPOLL 




CHECKPT 


MSGTYPE 




CODE 


PATH 




COUNTER 


SCREEN 




DATETIME 


SETEOF 




LOCOPT 




Outheader 


LOG 


SETSCAN 


Subgroup 


MSGEDIT 


SEQUENCE 




MSGFORM 


TERRSET 




MSGLIMIT 


TYPETABL 




CHECKPT 


LOG 




CODE 


MSGEDIT 


Outbuffer 


COUNTER 


PATH 


Subgroup 


CTBFORM 
LOCOPT 


lERRSET 




CHECKPT 


LOG 


Outmessage 


ERRORMSG 


MSGGEN 


Subgroup 


HOLD 


REDIRECT 



Figure 1 1 . Message Handler Subgroups and Macros 
1 44 OS/MFT and OS/MVT TCAM Programmer's Guide 



Selecting Message-Handler Functions 

Functional macro instructions perform the specific operations required for mes- 
sage segments being handled by the various subgroups of a Message Handler. 
Message segments are directed to the appropriate subgroup by the delimiter 
macros; the functional macros of the subgroup are then executed in the order in 
which they are specified within the subgroup. Functions provided by an MH 
include: 

• Message editing (insertion of date, time, and sequence number, insertion or 
removal of characters or character strings). 

• Validity checking (verification of source and destination codes and of sequence 
numbers in incoming message headers). 

• Routing messages to various destinations or alternate destinations, possibly by 
priority. 

• Maintaining counts and logs for message traffic on a line. 

• Error checking and handling (checking for errors in transmission and taking 
corrective action). 

• System control (interrogating or modifying activity on a system, line, or station 
basis, or specifying properties or limitations for messages). 

• Function selection (permitting dynamic selection of the functions to be per- 
formed on messages). 

MH Functions and Macros Defining the Functions 

The table below shows the various macros used to specify these functions. A 
brief description of the Message Handler functions provided by TCAM is given 
here. A complete description of these functions is found in the discussions of the 
individual macros in the Functional Macro Instructions section of this chapter. 

MH Functions Macros Defining the Functions 

Message Editing CODE, DATETIME, MSGEDIT, MSGFORM, 
SEQUENCE, SETEOM 

Validity Checking FORWARD, ORIGIN, SEQUENCE 

Routing COMMBUF, FORWARD, INITIATE, MHGET, 

MHPUT, MSGGEN, PRIORITY, REDIRECT 

Record Keeping CHECKPT, COUNTER, LOG 

Error Handling CANCELMG, CUTOFF, ERRORMSG, HOLD, 

MSGGEN, REDIRECT, RETRY, SLOWPOLL, 
TERRSET 

System Control CUTOFF, HOLD, INITIATE, LOCK, LOCOPT, 

SCREEN, SETEOF, MSGLIMIT, UNLOCK 



Message Editing 



Function Selection MSGTYPE, PATH, SETSCAN 



Six TCAM macro instructions— CODE, DATETIME, SEQUENCE, SETEOM, 
MSGEDIT, and MSGFORM — ^provide editing facilities. 



I 



Designing the Message Handler 1 45 



Validity Cliecking 



CODE, when specified in the inheader or inbuffer subgroup, translates the data in 
the buffer from the line code to EBCDIC, using a specified translation table. 
When specified in the outheader or outbuffer subgroup, translation is from 
EBCDIC to the line code. 

DATETIME inserts the date and the time at which the message is received by (or 
sent by) the MCP in the header. 

SEQUENCE, when specified in an outheader subgroup, inserts an output 
sequence number in the messages that are sent to a destination. 

MSGEDIT inserts or deletes a character or character string in the message. 

MSGFORM, when specified in an outheader subgroup, inserts blocking characters 
into outgoing messages, thereby dividing the messages into logical blocks of data. 
When specified in an inblock subgroup, characters are deleted at a user-specified 
interval. 

SETEOM defines the extent of a logical message. 



Three TCAM macro instructions — FORWARD, ORIGIN, and 
SEQUENCE — check the validity of fields in the message header. 

FORWARD verifies that the station codes specified as destinations in the message 
header are vahd destinations in the system. 

ORIGIN determines the station that entered a message by checking the origin 
field in the message header for the symbolic name of the station. The origin field 
is designated, during the design of the header and the Message Handler to contain 
the name of the originating station. 

SEQUENCE verifies that the input sequence number included in the message 
header by the station operator is valid; that is, that the number is one greater than 
the sequence number of the previous message from that station. To perform this 
function, SEQUENCE is included in an inheader subgroup. 



Message Routing 



Six TCAM macro instructions— COMMBUF, FORWARD, INITIATE, 
MSGGEN, PRIORITY, and REDIRECT — route messages to a particular destina- 
tion. 



COMMBUF routes broadcast messages to the destinations specified in the 
indicated TLIST macro. 

FORWARD routes messages to the destinations specified in the message headers 
or to the destinations specified by the FORWARD macro. 

INITIATE routes segments of messages to their destination as soon as they are 
received, without waiting for the whole message to arrive. 

MSGGEN generates a special response message and routes it immediately to 
either the originating or the destination station. The response message bypasses 
normal message handling, queuing, logging, and buffering functions. 



1 46 OS/MFT and OS/M VT TCAM Programmer s Guide 



Record Keeping 



Error Handling 



PRIORITY routes messages to their destinations according to priority levels 
specified either in the message header or by the PRIORITY macro. 

REDIRECT queues a message for an additional or alternate destination under 
certain error conditions, or unconditionally. 



Two TCAM macro instructions — COUNTER and LOG — keep records of the 
flow of messages in the system. 

COUNTER keeps a count of incoming or outgoing message segments or complete 
messages, depending on the subgroup in which the macro is issued. 

LOG places copies of segments or messages passing through the system on a 
sequential medium, such as magnetic tape. 



Nine TCAM macro instructions— CANCELMG, CUTOFF, ERRORMSG, 
HOLD, MSGGEN, REDIRECT, SLOWPOLL, TERRSET and UNLOCK when 
used in a message subgroup provide for error detection and handling. These 
macro instructions test for error conditions arising during transmission and 
handling of the message and take action accordingly. The nine macros are used in 
conjunction with a message error record, which is assigned to each message as it is 
handled. The meaning of each of the bits in the message error record is explained 
in Appendix B . Some error-handhng macros (CUTOFF, TERRSET) set bits in 
the message error record; the rest test the bits in the message error record. 

A five-byte bit configuration (called a mask ) is specified in some error-handling 
macros. When the macro is executed, the mask is compared to the message error 
record assigned to the message. If a 1 is detected in any bit position of both the 
mask and the message error record, the functions specified by the macro are 
performed. A is specified in a mask bit position when the error condition 
represented by the corresponding position in the message error record is to be 
ignored. (An operand of the error-handling macro may specify that the macro is to 
be executed only if all bits specified in the mask are on in the message error 
record.) 

The function specified by an error-handling macro may also be performed uncon- 
ditionally (that is, for all messages or message blocks, independent of the setting 
of the message error record) by either specifying a mask consisting entirely of 
zeros or not specifying a mask at all. 

The requirements of the application must be analyzed to determine which errors 
or conditions must be detected, and which can reasonably be ignored without 
degrading the performance of the system. The seven error-handling macro 
instructions provide varying methods by which corrective or control functions can 
be initiated when an error has been detected. 



CANCELMG cancels a message or a block if a specified error has occurred. 

CUTOFF checks for incoming buffers filled with identical characters (an indica- 
tion of station malfunction). In such a case, the appropriate bit is set in the 
message error record. CUTOFF also specifies the maximum number of characters 
allowed in a message; if the maximum is exceeded, reception is terminated and an 
error bit is set. 



Designing the Message Handler 147 



System Control 



ERRORMSG and MSGGEN send a specified message if a specified error has 
occurred. 

SLOWPOLL suspends further polling on a given Une when errors specified by the 
error mask occur. 

TERRSET sets a bit in the message error record to indicate, at the discretion of 
the user, that a user-defined error has occurred. 

HOLD suppresses the sending of messages to a station when an error specified by 
the mask has been detected; it is usually used to withold transmission to a inopera- 
tive station. 

UNLOCK removes a station from extended lock mode and optionally disables a 
switched connection if a specified error has occurred. 

REDIRECT sends a message to an additional or an alternate destination if a 
specified error has been detected. This function normally handles messages that 
cannot be sent to their intended destinations. 

RETRY tries again to contact a switched station. 

The FORWARD, ORIGIN, and SEQUENCE macro instructions set bits in the 
message error record when they detect an invalid destination, origin, and sequence 
number, respectively. 



Nine TCAM macro instructions— CUTOFF, HOLD, INITIATE, LOCK, ^ 

LOCOPT, MSGLIMIT, SCREEN, SETEOF, and UNLOCK— modify the tele- ^* 

communications system or provide dynamic control over the functions of the 
system. 

CUTOFF terminates transmission of an excessively long message. 

HOLD stops transmission of messages to a station known to be inoperative or 
unattended for a period of time making transmission undesirable. 

INITIATE sends message segments to their first destination before the entire 
message has been received and enqueued. 

LOCK maintains the connection between a station and an application program for 
the duration of a message and its response. This facility is used for fastest re- 
sponse during inquiry applications. 

LOCOPT provides access to fields of the option table, permitting examination and 
modification of the contents of the fields. 

MSGLIMIT limits the number of messages sent to or received from a station 
during a single transmission sequence. 

SCREEN modifies the WRITE operation for terminals with display screens. 

SETEOF indicates an end-of-file message for an appUcation program. 

UNLOCK removes a station from the LOCK condition. 



I 



1 48 OS/MFT and OS/MVT TCAM Programmer's Guide 



Delimiting Functions 



Function Modification 

Three TCAM macro instructions— MSGTYPE, PATH, and SETS CAN— permit 
modification of the functions of the Message Handler. The first two macros 
provide for variations in processing by the MH for different types of messages. 
SETSCAN permits modification of the scan pointer setting (discussed below) to 
allow processing of a field in the header in some order other than the normal 
sequential order. 

The STARTMH delimiter macro provides end-of-block checking for hardware 
and logical errors, and takes appropriate user-specified action when such errors 
are detected. These errors cause bits to be set in the message error record. 
STARTMH also provides for the automatic deletion of certain line-control 
characters, so that the user need not concern himself with them. Of the remaining 
delimiters, INBLOCK, INHDR, INBUF, INMSG, OUTHDR, OUTBUF, and 
OUTMSG provide path-switching facilities. Only the INEND and OUTEND 
delimiter macros have no functional capabilities. 

Order of Macro Specification 

Functional macros relating to an entire message segment (that is, MSGEDIT, 
LOG) may appear at any point within the subgroup in which they are used. The 
MSGFORM, MSGEDIT, and SETEOM functional macros should be specified in 
the inblock subgroup to process data across buffer boundaries. Macros relating to 
specific header fields (that is, ORIGIN, DATETIME) should appear in the same 
order within the inheader or outheader subgroup as the header fields appear 
within the header. In planning a format for message headers, the user may 
arrange the various header fields in any desired order within the header; the 
corresponding macros that act on those fields must be placed within the subgroup 
in the same order. These order-dependent macros involve either: 

• inserting a new field in the message header (for example, DATETIME), 

• making a decision at some point during header processing (for example, 
MSGTYPE), or 

• using a TCAM scanning routine to determine the contents of a specific field 
(for example, ORIGIN). 

The order in which macros are issued to act on specific header fields is important 
since a pointer (known as the scan pointer ), refers to the proper field when each 
macro gains control to act on that field. 



The Scan Pointer 



In handling a buffer, TCAM maintains a pointer at the current field in the 
message header. Some macro instructions use this pointer to locate the field on 
which they act and automatically move the pointer to the next field before passing 
control to the next macro. The user must be aware of the positioning of the scan 
pointer as he designs his Message Handler. 

There are basically two types of TCAM macro instructions that move the scan 
pointer automatically, without intervention by the user. Examples can be found in 
Figure 12. 

1. Certain macros (for example, SETSCAN, FORWARD) move the scan pointer 
until a user-specified character string is found. After these macros have com- 
pleted execution, the scan pointer is positioned on the last character acted 



Designing the Message Handler 149 



upon. In this case, it is assumed that the next character string is the field to be 
looked at by the next field-dependent macro in the Message Handler. 
2. Other macro instructions move the scan pointer a certain number of characters. ; 

There are three ways this number is determined. 

a. With certain macros (FORWARD, ORIGIN, SETSCAN), the user may 
specify expHcitly a number of nonblank characters to be considered as the 
next field. When execution of a macro is complete, the scan pointer is 
positioned on the last character that satisfies the count. 

Example: 

FORWARD DEST=3. If a destination field in a header reads NYbC, the 

scan pointer points to the C. 

b. Some macro instructions may be concerned with fields of varying length, 
such as FORWARD and ORIGIN. The scan pointer is moved past any 
blanks that might precede the field. The field is then scanned for a blank 
delimiter. When such a macro is completed, the scan pointer points to the 
character immediately preceding the blank delimiter that designates the end 
of the field. 

c. Some macros are concerned with fields whose length is specified imphcitly 
by coding the contents of the field in the macro itself. SETSCAN may 
search for a field with contents that match those specified in the macro; the 
position of the scan pointer after the macro executes is described in the 
discussion of the macro. The INITIATE, LOCK, MSGTYPE, PATH, 
PRIORITY, SCREEN, SETEOF, and UNLOCK macros have an optional 
conchars operand; when this operand is specified, the scan pointer is moved 
past any blanks preceding the next field in the message, and the contents of 
the field are compared with the conchars string. If the field and the conchars 

string match, the scan pointer points to the last character of the field; other- ^ 

wise, it is returned to the position it occupied before the comparison was l| 

made. 



( 



150 OS/MFT and OS/MVT TCAM Programmer's Guide 



Before DATETIME is issued: 






Message Header - 




















Buffer 
Prefix 


































7B 


15 


N 


Y 


K 


L 


A 


K 


Message 
Text 




(2) 


© © © © 


Position of Scan Pointer is at: 


(a) When the segment comes into the buffer. 


® After STARTMH and INHDR have been issued. 


© After SETSCAN X'15' has been issued. 


After ORIGIN has been issued. 


After FORWARD has been issued. 




After DATETIME is issued: 






Buffer 
Prefix 


7B 


15 


N 


Y 


K 


L 


A 


K 


6 


9 


• 





3 


7 


K 


2 


1 


• 


4 


5 


• 


5 





K 


Message 
Text 




The DATETIME macro causes the header contents to be shifted 16 spaces 


left to make room for the date and time. These are inserted and the 


Scan Pointer is positioned at . 



Figure 12. Scan Pointer Movement 



When a message segment is received for processing in an incoming group of an 
MH, the space reserved for expansion by the RESERVE= operand of the line 
group DCB macro is moved to the front of the segment and the scan pointer is 
positioned at the last reserved byte. If no reserve bytes were specified, the scan 
pointer points to the last byte of the buffer prefix. The buffer is then examined 
for the presence of a machine EGA sequence. If such a sequence is found, the 
scan pointer is moved to the last byte of the sequence. However, the poUing 
character used when the Auto Poll feature is active is not considered part of the 
machine EGA sequence. 



For an incoming message, the scan pointer is not necessarily at the end of the 
header when the inheader subgroup finishes executing. The header may have 



Designing the Message Handler 151 



additional fields that are to be operated upon by an outheader subgroup when the 
message is removed from its destination queue. In this case, when the message is 
removed from the queue, STARTMH and OUTHDR reposition the scan pointer 
to the last remaining reserve byte or, if there are no more unused reserve bytes, to 
the last byte of the prefix. If the user wishes to use an outheader subgroup to 
process the remaining fields of his header, he may use the SETSCAN macro to 
reset the scan pointer to the last byte of the last field processed by the inheader 
subgroup. 

Macro instructions in an MH should be placed in the same order within a sub- 
group as the fields of the header on which they act. The scan pointer controls 
access to these fields, progressing across the header from left to right as the 
various macro instructions are executed. The user may employ the scan pointer 
(using the SETSCAN macro) in his own routines to perform additional header 
analysis. However, he must take the responsibility of positioning the scan pointer 
to its proper position before executing the next TCAM macro. 

Handling Logical Messages 

Message transmission as discussed in other sections of this book defines each 
transmission from a station as a message. This may not correspond, however to 
the user's concept of a message. Some stations accumulate data in buffers before 
it is transmitted and permit no more than one buffer's worth in a transmission. 
Thus, if a user's message is longer than the buffer size, his message requires two or 
more transmissions. What the user sees in this instance as one message is seen by 
TCAM as several. Alternatively, some stations permit many units of data, such as 
cards, to be batched and sent as a single transmission. TCAM takes this to be one 
message, whereas to the user it may be many. 

Logical message definition enables TCAM to process messages on a logical basis 
as defined by the user independently of any physical boundaries imposed by the 
associated transmissions. When the user defines his messages as logical, TCAM 
performs either a blocking or a deblocking operation and then processes and 
queues the resulting data as a single message. For instance, when a single trans- 
mission contains several logical messages, TCAM deblocks the messages and 
independently processes and queues each. 

The concepts of TCAM design discussed in other sections of this book are not 
modified for handling logical messages; that is, messages received from stations 
are still processed through a Message Handler and queued in destination queues 
from which they are sent to an application program or another station. The 
execution of inheader, inmessage, inbuffer, outheader, outmessage, and outbuffer 
subgroups remain the same. The inblock subgroup processes logical messages in 
the incoming group. The INBLOCK delimiter macro instruction identifies the 
beginning of an inblock subgroup. 

The SETEOM macro instruction, executed in the inblock subgroup, deblocks and 
blocks incoming data to form logical messages according to user specifications. 
The inblock subgroup is specified after the STARTMH delimiter macro and 
before the inheader subgroup. The inblock subgroup and the INBLOCK macro 
instruction are described in Structure of the Message Handler and Delimiter 
Macro Instructions , respectively. 

See Mid-Batch Recovery in the section TCAM I/O Error-recovery Procedures 
for a discussion of treating permanent I/O errors detected in incoming and 
outgoing multiblock messages. 



152 OS/MFT and OS/MVT TCAM Programmer's Guide 



( 



Logical Message Formats 



The types of logical messages that may be included in a TCAM system depend 
upon the characteristics of the physical transmissions involved. These characteris- 
tics determine whether incoming messages are blocked or deblocked to form 
logical messages to be handled by the MCP. 

For instance, some devices may impose a physical limit on the size of a transmis- 
sion, such as the IBM 2740 Model 2 Communication Terminal that transmits data 
equivalent to the size of its buffer, and input from a card reader that also may 
require fixed-length messages. Other devices may not impose such physical 
limitations, such as the IBM 1060 Data Communication System, and a 2780 Data 
Transmission Terminal that features multiple-record transmissions. Examples of 
logical messages formed from both kinds of these devices follow. In the examples, 
a physical transmission refers to the amount of data entered on a line during an 
entire transmission sequence (from the first byte of data in a message to the 
end-of -transmission character). 



Blocking Incoming Messages 



Incoming messages can be blocked to construct logical messages to be handled by 
the inblock subgroup. No incoming transmission will contain all the data that is to 
constitute the final logical message. 

In blocking two incoming physical transmissions to construct a single logical 
message, the user may specify that TCAM truncate any data appearing after the 
end of the logical data (after the EOM indicator) in the second physical transmis- 
sion; this is accompUshed by specifying PROCESS=NO on the SETEOM macro 
in the MH handling these physical transmissions. 

Example: 

Constructing a logical message by blocking two physical transmissions. Input is 
from an IBM 2740 Model 2, where the size of the logical message is greater than 
the terminal buffer size. For this type of message, the user specifies that only one 
logical message is to be processed (resulting in truncation of any data in the 
second buffer following the end of the logical message). 



E OT 



■ Logical Message ■ 



E E 

O o 

M T 



-Truncated 



In the example above, blocking is done on incoming data from a device that 
imposes a physical limit on the amount of data that may be entered for a single 
transmission sequence. The next example illustrates blocking a series of incoming 
logical blocks of data to construct a single larger logical message. The incoming 
logical blocks of data are all included in a single physical transmission. This 
procedure requires that the SETEOM macro specify PROCESS=NO. 

Example: 

Constructing a logical message by blocking multiple logical messages. Input is 
from an IBM 1060 Data Communication System where incoming logical messages 
are blocked according to the location of a user-specified character (EOM indica- 



Designing the Message Handler 153 



tor) that delimits the end of the last logical block to be included in the logical 
message being constructed. Incoming logical messages are referred to as blocks. 



1st Block 



E 
O 
B 



2nd Block 



E 
O 
B 



3rd Block 



E E 
O O 

MB 



d 



-Logical Message 



Deblocking Incoming Messages 



Deblocking always occurs on incoming data that consists of variable-length logical 
blocks of data separated by EOM indicators. The last EOM indicator in the last 
logical block of data is followed by an EOT line control character (the 
EOM/EOT sequence indicates to TCAM that this is the end of the physical 
transmission). Each imbedded logical block of data in a given physical transmis- 
sion may contain a header and may be extracted for processing and routing to a 
particular destination queue. The boundaries of each logical block are determined 
when the buffer containing a block passes through the input MH and is processed 
by the SETEOM macro instruction. Discussions in other parts of this book on 
length and format of messages apply also for deblocked logical messages. 



Example: 

Extracting logical messages by deblocking logical blocks of data in a physical 
transmission. Input is variable records from an IBM 2780 Data Transmission 
Terminal. Each variable input record on a card is delimited by a character that 
signifies EOM (end of logical message). 






Physical Transmission ■ 
E 

M 



iJ 



E E 
O O 
M T 



V 

1st 

Logical 

Message 



2nd 

Logical 

Message 



— V 

3rd 

Logical 

Message 



>^ 

4th 

Logical 

Message 



If part of a physical transmission has been received from a station, output to that 
station is not sent until the EOM/EOT sequence is received from the station 
indicating the end of the physical transmission. 

Converting Incoming Data to Logical Messages 

Conversion of incoming data in a physical transmission to logical message is 
achieved by using the SETEOM macro instruction in the inblock subgroup of an 
MH handling incoming messages. The SETEOM macro instruction is discussed in 
Functional Macro Instructions. 

The user specifies on the SETEOM macro which delimiter character or which 
length of data, or both, determine the limits of a logical message. When both are 
specified, the first condition met determines the end of a logical message. The 
SETEOM macro also permits the user to remove EOM characters from incoming 
logical messages. 



154 OS/MFT and OS/MVT TCAM Programmer's Guide 



When TCAM detects an EOM condition in an incoming transmission, it needs to 
know how to handle the data, if any, following the EOM indicator. The SETEOM 
I macro indicates to TCAM whether it is to discard any remaining portion or to 

process it as the first buffer of another message. Subsequent buffers begin 
processing at the INBLOCK deUmiter macro instruction. 

Execution of SETEOM may force an EOM condition; for instance, if the input to 
an MH is cards containing variable-length records (such as 2780 batch input), and 
the last card in the hopper ends in the middle of a message, TCAM assumes an 
EOM condition and the last card is the end of the message. Another instance of 
forcing an EOM condition is the occurrence of a permanent transmission error 
before TCAM detects the User-specified EOM. In this case an EOM is forced for 
the last buffer successfully transmitted. In a dial network, for instance, if an 
operator hangs up before an entire logical message is entered (or if a disconnec- 
tion is caused by some other means), TCAM forces an EOM condition for the 
message being entered. In either of these cases of forced EOM, the logical 
message is processed through the MH. 

TCAM, however, does not always assume an EOM condition. For instance, if 
input is from a 2740 Model 2 and the message is directed to an MH that is to 
construct a single logical message from two or more physical transmissions 
(PROCESS=NO is specified on the SETEOM macro), the input message must 
contain an EOM character in the second (or a subsequent) buffer. Otherwise, the 
2740 Model 2 cannot accept further output from the CPU (TCAM is still waiting 
for the user-specified character that designates the end of the logical message). 

The user may not issue successive SETEOM macros in the same Message Handler 
^, in order to process nested logical messages. That is, if a SETEOM macro is used 

¥ to extract a logical message (message A) from a series of logical messages entered 

during one physical transmission, another SETEOM macro cannot be issued to 
find further logical messages embedded within message A. 

The buffer trace facility, provided by the TRACE= and COMWRTE= operands 
of the INTRO macro instruction, provides a dump of deblocked logical messages. 

Logical Message Flow Within the System 

Message flow in a TCAM system remains the same for logical messages as for 
physical messages (message flow for physical messages is discussed in Message 
Flow Through a Message Handler in this chapter). Incoming data is processed 
through an MH where it is converted into logical messages by the SETEOM 
macro. The logical messages are then routed to their destination queues independ- 
ently of any incoming physical message boundaries. Figures 13 and 14 show 
examples of message flow within the system when logical messages are being 
handled. 

In Figure 13, message flow is shown for a logical message that is constructed from 
two physical transmissions (SETEOM specifies PROCESS=NO, resulting in 
truncation of data following the EOM character). The EOM character is con- 
tained in the second physical transmission. 

1. The station T responds to polling and enters data for the first physical trans- 
mission to the CPU. This first physical transmission fills the buffers that are 
allocated and deallocated according to the program-controlled interruption 
option selected for the station (see the PCI= operand of the line group DCB 
I macro instruction) . 



Designing the Message Handler 155 



Logical Message ^ 

Physical Transmissions l- 



Header 



Text 



Text 



E 
■ M 



t — ^^-n 



-> T C 







PI 



P2 



.o| 



STARTMH LMD=YES 



INBLOCK 

SETEOM PROCESS=NO 
INHDR 

INBUF 

INMSG 



INEND 



Outgoing Subgroups 



Destination 
Queue 



o 



J 



Legend: PI, P2 
L 

EOT 
EOM 



physical transmissions 

logical message 

end of physical transmission 

end of logical message 

portion to be dropped 

terminal 



Figure 13. Flow of Logical Message Formed by Blocking Two Physical Transmissions 

2. All buffers of the first transmission are processed through the inblock sub- 
group, and the SETEOM macro instruction is executed for them. 

3. The first transmission does not contain an EOM character. The buffers pass 
through the remainder of the MH and are queued to their destination, but 
TCAM considers the logical message to be incomplete; that is, the last buffer 
of this transmission is not processed as the last buffer of the logical message. 
However, the line is reactivated. 

4. The line is now available for any station that has data to enter, including 
station T, which is polled first. If station T is not ready to enter data for the 
second transmission, another station is polled. (TCAM line scheduling is the 
same as for a TCAM system that is not handling logical messages.) 

5. When the second transmission from terminal T arrives at the CPU, its buffers 
are passed to the MH in the same manner as the first transmission. 

6. These buffers are processed by the SETEOM macro; they proceed through 
the remainder of the MH and are queued until the EOM condition is satisfied. 
One difference in MH processing of logical messages is that the second 
transmission is not a new message, but the continuation of the logical mes- 
sage. Therefore, the first buffer of the second transmission is not processed 
as a header buffer, but as a text buffer. 



1 5 6 OS/MFT and OS/M VT TCAM Programmer's Guide 



7. When TCAM detects the EOM, the remaining portion (if any) of the current 
buffer is truncated. The buffer containing the EOM character is processed by 
the rest of the MH as the last buffer of the message. 

8. After TCAM detects the EOM indicator, subsequent buffers of the same 
transmissionare truncated also. They are returned to the buffer pool without 
being processed by the MH and without being queued. 

9. The inmessage subgroup is executed for the logical message when its last 
buffer has been handled. This inmessage processing, performed for the 
buffer containing the EOM, is delayed until block checking is performed for 
the block containing the EOM. 

10. The line is then reactivated and the logical message is ready to be sent to its 
destination (either an application program or a station). 

In Figure 14, message flow is shown for logical messages formed by extracting two 
logical messages entered in a single physical transmission (such input might come 
from an IBM 1060 Data Communication System or an IBM 2780 Data Transmis- 
sion Terminal). 

The EOM character appears as part of the input stream at the end of each logical 
message; the last EOM is followed by EOT. (The SETEOM macro specifies 
PROCESS=YES, resulting in successive logical messages being handled by the 
incoming MH until an EOM is followed by an EOT.) 

1. Station K responds to polling and enters its variable-length messages in a single 
transmission sequence. The message fills -the buffers, which are allocated and 
deallocated according to the program-controlled interruption option selected 
(see the PCI= operand of the line group DCB macro). This example requires a 
value of N or X for the PCI= operand. 

2. All buffers containing any data of the first logical message are processed in the 
inblock subgroup where they are examined by the SETEOM macro. 

3. The first buffer of the entire incoming transmission is processed through an 
inheader subgroup as the header buffer for the first logical message. 

4. TCAM detects the EOM character that delimits the first logical message and 
gets a new buffer in order to separate the first logical message and any remain- 
ing portion of the EOM buffer. This remainder becomes the header buffer for 
the second logical message and is assigned to the MH where processing begins 
at the beginning of the inblock subgroup. 

5. The buffer containing the EOM character that ends the first logical message is 
the last buffer of the first logical message; it proceeds through the MH and 
causes the inmessage subgroup to execute. Macros in the inmessage subgroup 
that are executed for the first logical message also handle error conditions for 
all the input data since block checking is performed before processing later 
portions of the first logical message. 

6. The first logical message is ready to be sent to its destination. 

7. Processing of the second logical message is done just as it was for the first. 



Designing the Message Handler 157 



LI 



Logical Messages 



. Header 



E 
O 

Text ^!^' Header 



L2 



Text 



E 

O 

"M 



Physical Transmission L. 



JE 



G> 



STARTMH LMD=YES 



r#»INBLOCK 

j SETEOM PROCESS=YES 

I 

INHDR 



INBUF 



INMSG 



INEND 



Outgoing Subgroups 



Destination 
Queue 



o 



Legend: 



P 

L1, L2 

EOT 

EOM 



physical transmission 
logical messages 
end of physical transmission 
end of logical message 



H 



Figure 14. Flow of Logical Message Formed by Deblocking a Physical Transmission 



Message Headers for Logical Messages 

In a TCAM network that does not define logical messages (see the SETEOM 
macro), a header begins each physical transmission. This concept is modified 
when the SETEOM macro is coded to define logical messages, so that a header 
begins each logical message . Thus, if a logical message is constructed from two 
incoming physical transmissions (such as blocking two physical transmissions from 
a 2740 Model 2), only one header is processed for the logical message. 



1st J 

Physical i 

' Transmission "H 



^ Logical . 
Message 



2nd ^ 

Physical ^ 

■ Transmission"^ 



( 



1 5 8 OS/MFT and OS/M VT TCAM Programmer's Guide 



In this example, the SETEOM macro specifies PROCESS=NO. The first buffer 
of the second physical transmission is processed as a continuation of the logical 
message, that is, as a text buffer. 



If the user appUcation is such that the size of the messages being entered coincides 
with the limit imposed by the input device (such as buffered terminals and some 
card readers), blocking is not required; thus, the number of headers needed is the 
same for both physical transmissions and logical messages. 



E 


E 








M 


M 


W/////////////M 


y////////MM^^^ 


1 

E 
1st 


1 

E 
2nd O 


Logical j 


Logical j 
^ — Message — ^ 


^1st J 
Physical 
Transmission 


^2nd ^ 
Physical 
Transmission 



In this example, the SETEOM macro specifies PROCESS=NO. A physical 
transmission is equivalent to a logical message, and the same number of headers is 
required for physical transmissions as for logical messages. 

The preceding examples consider header requirements for entering individual 
logical messages, where one or more physical transmissions are required. 
Suppose/, however, that a network includes devices such as the IBM 1060 Data 
Communication System and the IBM 2780 Data Transmission Terminal (with the 
multiple record transmission feature), where a single physical transmission com- 
prises many logical blocks of data (batch input), each to be treated as a message. 

In a network where the user does not define logical messages, batch input requires 
a single header. However, by defining logical messages with the SETEOM macro, 
each incoming, imbedded logical block of data is a message, and each block 
requires a header. 



,E 
o 

M 



E 

o 

M 



E 
O 
M 



1st 



2nd 



^^ Logical ^i^ Logical 
Message 

■ Physical 
Transmission 



E 

O 

3rd T 

Logical-^ 

Message ' 



In this example, if the user does not define logical messages for his system, his 
batch input requires only one header, and TCAM processes all the data in the 
physical transmission on the basis of the single header (that is, TCAM treats the 
input as a single message). However, if user requirements dictate that the data in 
this batch input can best serve the purpose by including logical messages, then 
each imbedded logical block must start with a header for TCAM to initiate header 
processing for each logical message (thus, TCAM can treat each incoming logical 
block of data as a message, and multiple destinations can be defined for the batch 



Designing the Message Handler 159 



input from a station). The SETEOM macro must specify PROCESS = YES in 
order for TCAM to process the individual logical messages described in this 
example. 

Coding Considerations for Logical Message Use 

This section considers the coding requirements for the user who defines logical 
messages for his TCAM network. The table below lists the macros and only those 
operands that need to be considered for defining data sets and stations; it also Usts 
some delimiter and functional MH macros that need to be considered. The table 
lists only those macros and operands concerning logical messages. Other sections 
of the book contain complete descriptions of these and other macro instructions 
(see the Macro Directory in the front of this book). 

Of the macro instructions Usted below, only the SETEOM functional macro is 
limited to use with logical message handling. The remaining macro instructions 
may be used in handling physical transmissions in a TCAM system that does not 
define logical messages; of these, however, some operands are restricted to use 
with logical message (PCI=X on the line group DCB macro, LMD= on the 
TERMINAL macro, and LMD= on the STARTMH macro). 



Area of 
Code 

Defining 
data sets 



Macro 

line 
group DCB 



Operand 




Remarks 

X specifies that after a buffer 
is filled (receive operations) 
or emptied (send operations), a 
PCI occurs during the filling 
or emptying of the next buffer. 
The first buffer is not deallo- 
cated, but a new buffer is allo- 
cated. Buffer deallocation 
occurs at the end of transmis- 
sion, or when an EOB/ETB control 
character is sent, if EOB/ETB 
checking is specified in the 
STARTMH macro. 



Defining 
stations 



TERMINAL LMD= J YES ) 

\NO / 



MB= (YES) 
INO / 



PCI=N or X must be specified if 
the SETEOM macro specifies 
PROCESS=YES, in order to ensure 
that logical messages are not 
deblocked until block checking 
is performed. Otherwise, a 
logical message containing an 
error could be routed to its 
destination. 

This operand specifies whether 
logical messages are to be 
transmitted either to or from 
this station. LMD=YES must be 
coded. 

Provides mid-batch recovery on 
input and output operations on 



( 



1 60 OS/MFT and OS/M VT TCAM Programmer s Guide 



logical messages in a TCAM network. 
Requires that LMD=YES be specified 
on this TERMINAL macro for any station 
entering or accepting logical messages 
and for which mid-batch recovery is 
desired. LMD=YES must be specified on the 
STARTMH macro of the MH handling logical 
messages (for incoming operations, 
LEVEL =BLK must be specified on the 
CANCELMG macro in the inmessage 
subgroup; for outgoing operations, 
LEVEL=BLK must be specified on the HOLD 
macro in the outmessage subgroup). 



^^ Designing 

^ Message 

Handlers 



STARTMH 



LMD=JYES) 
INO / 



Note: // stations specifying 
either LMD^YES or MB=YES are 
defined on the same line with 
stations (other than concentrators, 
see Defining the Network in 
Appendix J that do not specify 
either of these two operands, the 
first TERMINAL macro used to define 
stations on this line must be for a 
non-concentrating terminal not 
specifying either of these two 
operands. 

This operand specifies whether 
logical messages are to be 
handled by this MH. LMD=YES 
must be coded. 



INBLOCK 



PATH=(opfield, 
switch ) 



Delimits the beginning of an 
inblock subgroup and is required 
if this MH: 



includes a SETEOM macro for 
handling logical messages, or 
includes a MSGEDIT macro for 
handling character strings that 
cross buffer boundaries, or 
includes a MSGFORM macro for 
deleting multiple character 
strings on a count basis. 



The inblock subgroup must 

precede the inheader subgroup. 

Functional macros that may 

be coded in this subgroup are CODE, 

COUNTER, LOG, LOCOP, MSGEDIT, 

MSGFORM, MSGLIMIT, PATH, SETEOM, and 

TERRSET. If coded before the 

SETEOM macro they execute for all 

the data in the physical transmission; 



Designing the Message Handler 161 



CANCELMG LEVEL=(BLK) 

i MSG f 



CODE [(tablename]] 

) NONE > 
((register) ) 



if coded after SETEOM, they execute 
individually for logical messages. 

Specifies mid-batch recovery for errors 

detected in incoming multiblock 

messages. If mid-batch recovery is 

required, LEVEL=BLK must be specified in 

the inmessage subgroup (specify only 

once; CANCELMG must be the first functional 

macro in the subgroup). 

Translates data in the buffer 

being handled and tests for operator 

commands. The following considerations 

apply for logical messages that are extracted by 

deblocking data in an incoming physical 

transmission. 



COUNTER 



opfield 



• When coded before the SETEOM macro, all data 
related to this transmission is translated. Logical 
messages are to be checked for operator control 
characters,another CODE macro must be coded 
in the inheader subgroup (and it must specify 
NONE). 

• When coded after the SETEOM macro, 
functions the same as for physical transmissions 
(translates,but must be coded in the inheader 
subgroup to check for operator control charac- 
ters). 

Counts either logical message 
segments or physical message segments, 
depending on its position relative 
to the SETEOM macro and whether 
the PROCESS = operand of SETEOM 
specifies YES or NO. 

When SETEOM specifies PROCESS=NO, 
all resulting logical messages are 
counted. 



/4 

i ' 



HOLD 



LEVEL= 



[MSGl 
LBLKJ 



When SETEOM specifies PROCESS=YES, 
the position of COUNTER relative to 
SETEOM determines what is counted. 
IF COUNTER is coded before SETEOM, 
the count reflects all the buffers 
forwarded to the MH in the transmission 
sequence. If coded after SETEOM, 
the count reflects each buffer of each 
resulting logical message. 

If this operand is omitted or if 

it specifies MSG, the HOLD macro 

provides the same function as 



i 



1 62 OS/MFT and OS/MVT TCAM Programmer's Guide 



for physical messages (see the 
description of the HOLD macro in 
Functional Macro Instructions ). 

LEVEL =BLK specifies mid-batch 
recovery for errors detected in 
outgoing multiblock messages to 
a switched station. If mid-batch 
recovery is required, LEVEL=BLK 
must be specified in the outmessage 
subgroup (specify only once; HOLD 
must be the first functional macro 
in the subgroup). 



LOCK 



Requires that PROCESS = NO be 
coded on the SETEOM macro. Used 
only for a logical message con- 
structed by blocking two or more 
incoming physical messages. Provides 
the same functions as for physical 
messages, except on a logical message 
basis. Lock is achieved after EOM 
character is detected (implying that 
multiple physical transmissions may have 
been received). See the description 
of the LOCK macro in Functional 
Macro Instructions. 



MSGFORM 



Removes line control characters (on a 
count basis) from incoming messages. 
MSGFORM must be coded in the inblock 
subgroup before any other macro that 
might cause data movement. 



MSGLIMIT 



SETEOM 



ENDCHAR=rchars "I 
LppfieldJ 



Provides the same function as 
for physical messages. The count 
for MSGLIMIT is updated for each 
physical transmission sequence. 

This macro, restricted to use in 
the inblock subgroup, controls 
the amount of data in logical 
messages, determines what is 
done with data following EOM, 
and permits removal of EOM char- 
acters. 



The ENDCHAR= operand specifies 
the character or character 
string used to delimit the mes- 
sage. This operand is required 
if the LENGTH = operand is not 
coded (otherwise, it is optional). 



Designing the Message Handler 1 63 



chars specifies one to eight 
nonbiank characters in either 
character (C* ' or CLn' ') or 
hexadecimal (X' ' or XLn* ') 
format 

opfield is the name of a field 

defined by an OPTION macro containing 

the character or character string. 

The first byte of the option field 

contains the length of the delimiter, 

followed by the delimiter. 



LENGTH= 

((integer (,opfield2) 



Jopfieldl* 



Specifies the length of the mes- 
sage. Must be specified if the 
ENDCHAR= operand is not coded; 
otherwise, this operand is 
optional, integer specifies 
a decimal integer that may be 
up to 65535. 



PROCESS=(YESl 
(NO j 



opfield 1 is the name of a halfword 
defined by an OPTION macro con- 
taining the length of the message. 

opfield! is a halfword option 
field set to zero (counts bytes 
already received). 

Determines whether any incoming 
data following EOM is processed 
or discarded. 



YES causes data following the 
EOM to be processed in the same 
manner as the previous data. 



REMOVE=jYES) 
\NO I 



NO causes processing for the 
first logical message only. 

Removes EOM characters from 
buffers containing logical mes- 
sages (or partial logical mes- 
sages). 



YES causes EOM characters to be 
removed from incoming buffers 
containing parts of one or more 
logical messages. 



NO causes EOM characters to remain 
in the buffer in which they appear. 



( 



1 64 OS/MFT and OS/MVT TCAM Programmer's Guide 



Message Flow Through A Message Handler 

Figures 15 and 16 illustrate the overall flow of a message through Message 
Handlers written for two representative TCAM applications. After briefly 
considering the overall flow, the path of a message within a single incoming or 
outgoing group is described. If logical messages are being handled, see Logical 
Message Flow Within the System in the preceding section. 

Figure 15 illustrates the flow through a single MH of a message to be switched 
from one station to another that requires no processing by an application program. 
The incoming message is routed by STARTMH to the incoming group of the MH 
assigned to the Une (by the MH= operand of the DCB macro for the line group in 
which the line is included). After being processed by the incoming group, the 
message is placed on the destination queue for the station to which the message is 
to be routed. This queue may be on a direct-access storage device, or it may be in 
main storage. TCAM obtains messages from the destination queue on a first- 
ended first-out basis within priority groups. STARTMH then routes the message 
from the destination queue to the outgoing group of the MH assigned to the line 
on which the destination station is located. After being handled by the outgoing 
group, the message is transmitted to the destination station. 



Message 
entered at 
remote 
station 



N 



Message 
accepted at 
destination 



Incoming 
Group of MH 
for line group 



Destination 
queue 



Outgoing 
Group of MH 
for line group 



Figure 15. Message Flow for a Switched Message 

Figure 16 illustrates the more complicated message flow for a message that is 
received, routed to an application program, and then transmitted to a destination 
station. The message is processed first by the incoming group of the MH handling 
messages for this line, then placed on the destination queue for the appUcation 
program (this queue is created by a TPROCESS macro). The outgoing group 
created especially for the application program and assigned to it by the MH= 
operand of a PCB macro processes the message when it is removed from the 
destination queue; the message is then placed on the read-ahead queue , a special 
queue to which access is gained by GET or READ macros issued in the applica- 
tion program. After being processed by the application program, the message is 
returned to a process queue by PUT or WRITE macros and is handled by the 
incoming group of the MH assigned to the application program by the MH= 
operand of the PCB macro for that application program. The message is routed 
by this incoming group to the destination queue for the station that is to accept 
the message. It is then handled by the outgoing group of the MH assigned to the 
line and transmitted to the destination station. 



Designing the Message Handler 1 65 



Message 
entered at 
remote 
station 



I ncom.i ng 
Group of MH 
for line group 



Destination 
queue for 
application 
program 



In Figure 16, two incoming and two outgoing groups are used in iiandling the 
message. One incoming and one outgoing group are assigned to the Une, and one 
of each group is assigned to the appUcation program. The user might provide 
these groups by designing one MH for his Une and another for his application 
program; or he might design a single MH and assign it to both the line and the 
apphcation program. This single MH would have some subgroups that would be 
executed only for messages coming in from or going to a station on the line, and 
other subgroups that would be executed only for messages being sent to or 
received from an appUcation program. For a description of how this selective 
execution is accomplished, see Variable Processing within a Message Handler in 
this chapter. 



Outgoing 
Group of MH 
for application 
program 



Incoming 
Group of MH 
for application 
program 



Read-ahead 
queue 



Application 
program 



Message 

accepted 

at destination 

station 



M 



Outgoing 
Group of MH 
for line group 



4 



Destination 
queue for 
accepting 
station 



Figure 1 6. Message Flow for a Message that is Processed by an Application Program 



For a more thorough description of the flow of a message through a TCAM 
system, see Message Flow within the System in the TCAM Concepts and 
Facilities publication. 



Message Flow within an MH Group 

That portion of a message contained within one main-storage buffer is caUed a 
message segment . When a message segment arrives for processing by a Message 



< 



1 66 OS/MFT and OS/MVT TCAM Programmer's Guide 



Handler, STARTMH determines whether the segment is part of an incoming or 
outgoing message and routes it to the incoming or outgoing group, as appropriate. 
STARTMH also determines whether the segment contains part of a multiple- 
buffer header. A multiple-buffer header is a message header that occupies more 
than one buffer. Message segments containing part of a multiple-buffer header go 
through the inheader and outheader subgroups in a special manner, described 
below. 

The flow through an MH assigned to a Une group of a message that does not have 
a multiple-buffer header is illustrated in Figure 17. After a segment has been 
routed to an incoming or outgoing group, the INHDR or OUTHDR macro deter- 
mines whether this is the first segment of a message, or a segment other than the 
first. Only the first segment of a message not having a multiple-buffer header is 
routed to the inheader or outheader subgroup (if present). All segments 
(including the first) are normally processed/ by the inbuffer or outbuffer sub- 
groups present in the group handling the message. The macros in the inheader, 
outheader, inbuffer, and outbuffer subgroups are executed on a segment-by- 
segment basis, while those in the inmessage and outmessage subgroups are not 
executed until the entire message has been handled by the other subgroups. The 
inmessage subgroup is executed when the last message segment reaches the 
inmessage delimiter. The outmessage subgroup is not executed until after the 
entire message has been transmitted to the destination station or sent to the 
appUcation program. 

In Figure 17 there are only three subgroups per group, and it is assumed that all 
the subgroups are involved in handling the message. Since some subgroups are 
optional, a group may have fewer than three subgroups, but a group may also have 
many more than three subgroups by including more than one subgroup of a given 
type. Moreover, not all subgroups included in a group need be involved when the 
group handles a particular message; TCAM provides selective execution of 
subgroups according to the setting of a path switch. This variable-processing 
capability is discussed later in this chapter. 



Designing the Message Handler 1 67 











UCA 


PkCD 


TEXT 




















STARTMH 




First message segment 




Inheader 

or 
Oufheader 
Subgroup 






Inbuffer 

or 
Ouf buffer 
Subgroup 






Inmessage 

or 
Outmessage 
Subgroup* 


1 










IINMSGor OUTMSG 
1 








1 

1 




Destination queue 
or remote station 




INEND 

or 
OUTEND 























TFVT 


1 


















STARTMH 




Subsequent message segment 


Inheader 

or 
Outheader 
Subgroup 


1 








ilNHDR or ( 

1 


DUTHDR 










Inbuffer 

or 
Outbuffer 
Subgroup 








Inmessage or 
Outmessage 
Subgroup* 






INEND 

or 
OUTEND 












Destination queue 
or remote station 

















* Note: Functional macros in the Outmessage Subgroup are not executed 
until after the entire message has been sent. 



Figure 17. Flow of a Two-Segment Message with a Single-Buffer Header through an MH 



i 



1 68 OS/MFT and OS/MVT TCAM Programmer's Guide 



Multiple-Buffer Header Handling 

Figure 18 illustrates the flow through an MH assigned to a line group of a two- 
segment message having a multiple-buffer header. The main difference between 
this type of flow and that described above for a message not having a multiple- 
buffer header is the way in which the inheader and outheader subgroups are 
executed. 

The first segment of a message having a multiple-buffer header consists entirely of 
header information. This first segment does not go through the entire inheader or 
outheader subgroup. Once the. last field in this segment has been processed by 
field-dependent instructions in the inheader or outheader subgroup (once the scan 
pointer has advanced to the end of the buffer), TCAM saves the address of the 
next (unexecuted) inheader or outheader instruction and also saves the contents 
of all registers specified by the USEREG= operand of the INTRO macro. The 
first segment continues through the inheader or outheader subgroup, but only 
those macros that do not depend on the location of the scan pointer or upon 
certain data being in the buffer are executed for it. Among such macros are 
CHECKPT, CODE, COUNTER, LOCOPT, LOG, MSGFORM, MSGLIMIT, 
and TERRSET. The INITIATE, LOCK, MSGTYPE, PATH, SCREEN, 
SETEOF, and UNLOCK macros execute if the conchars operand is not coded for 
them. The FORWARD macro executes if the destination is specified in the macro, 
rather than in the message header. The PRIORITY macro executes if the priority 
level is specified in the macro and no conchars operand is coded. 



Designing the Message Handler 1 69 















1 








HtADcK j 










STARTMH 




First message segment 


Inheader 

or 
Outheader 
Subgroup 






Inbuffer 

or 
Outbuffer 
Subgroup 






Inmessage 

or 
Outmessage 
Subgroup* 


1 








[[NMSG or OUTMSG 
1 




. 




1 

1 




Destination queue 
or remote station 




INEND 

or 
OUTEND 













4 











HEADER 


TP 


\/T 






1 t/\l 










STARTMH 






Next message segment 








Inheader 
or 






Outheader 
Subgroup 








Inbuffer 

or 
Outbuffer 
Subgroup 






Inmessage 

or 
Outmessage 
Subgroup* 






INEND 

or 
OUTEND 












Destination queue 












or remote station 





* Note: Functional macros in the Outmessage Subgroup are 
not executed until after the entire message has been 
sent. 

Figure 18. Flow of a Two-Segment Message with a Multiple-buffer Header through an MH 



i 



1 70 OS/MFT and OS/MVT TC AM Programmer's Guide 



In Figure 18, a dotted flow line through the inheader/outheader section indicates 
that the scan pointer has reached the end of the first header segment, and only 
those macros listed above are being executed for it. 

When the second segment is ready for handUng, STARTMH routes it directly to 
the inheader or outheader instruction whose address was saved, rather than to the 
INHDR or OUTHDR macro at the beginning of the subgroup. (At this time, 
TCAM also restores the contents of the registers specified by the USEREG= 
operand of the INTRO macro.) 

If the CODE, FORWARD, PRIORITY, or INITIATE macros are issued in an 
inheader subgroup handling multiple-buffer header segments, these macros must 
be specified early enough in the subgroup so that they act upon the first message 
segment. This also appUes to PATH macros issued in an inheader or outheader 
subgroup, if all segments of the message are to be handled alike. 

Note: Figure 18 contains only one of each kind of subgroup. For messages 
with multiple -buffer headers, the use of multiple inheader or outheader 
subgroups is severely restricted; all such subgroups must begin processing on 
the first message segment. In addition, if part of a multiple -buffer header is 
to be processed by an inheader subgroup and the rest is to be processed by 
an outheader subgroup, both subgroups must begin execution on the first 
message segment. 

The execution of an inheader or outheader subgroup can begin only on the first 
segment of a message. This is because the INHDR or OUTHDR macro for a 
particular inheader or outheader subgroup causes all message segments except the 
first to bypass the subgroup. One inheader or outheader subgroup can handle a 
multiple-buffer header because the INHDR or OUTHDR macro does not get the 
opportunity to check segments other than the first (due to the way in which 
multiple-buffer headers are handled). If a second inheader or outheader subgroup 
is coded to begin execution midway through the second segment, it will never 
execute; its INHDR or OUTHDR macro will route incoming segments directly to 
the next delimiter. 

Note: // an out buffer subgroup precedes an outheader subgroup that process- 
es more than one segment of a message having a multiple -buffer header, the 
out buffer subgroup is executed for the first segment only. 



Multiple-Buffer Header Processing Across Buffers 







Will 


Will Not 








Cross 


Cross 


Conditional 


Macro 


N/A 


Buffers 


Buffers 


(Note 1) 


CHECKPT 


X 








CODE 


(Note 2) 








COUNTER 
DATETIME 
FORWARD 
INITIATE 


X 
X 


(Note 3) 


DEST in message 


X 



Designing the Message Handler 171 



Macro 


N/A 


Will 

Cross 

Buffers 


Will Not 

Cross 

Buffers 


Conditional 
(Note 1) 


LOCK 








X 


LOCOPT 


X 








LOG 


X 








MSGEDIT 






X 




MSGFORM 


X 








MSGLIMIT 


X 








MSGTYPE 








X 


ORIGIN 




(Note 4) 






PATH 








X 


PRIORITY 




(Note 5) 






SCREEN 








X 


SEQUENCE 


output only 




input only 




SETEOF 








X 


SETSCAN 




chars 


integer 

POINT=BACK 

chars,RETURN= 





TERRSET X 

UNLOCK X 

Note 1 : Will cross if conchars is not specified, or if entire character string 

is in a subsequent buffer. 
Note 2: Except that an operator command must be complete in a single 

buffer. 
Note 3: Will cross if destination is in the macro or an option field and 

the macro is executed for the first buffer. 
Note 4: Will cross but origin may not be known on dial lines for first 

buffer. 
Note 5: Will cross if conchars is not specified and priority level is in macro. 

Variable Processing Within a Message Handler 

The path of a message through a Message Handler may be varied dynamically 
using the PATH and MSGTYPE macro instructions. By permitting different 
operations upon different types of messages directed to the same Message Han- 
dler, these macros enhance the versatility of the Message Handler. By judiciously 
using PATH and MSGTYPE macros, the user can design one Message Handler 1 

that will handle messages having a variety of header formats and that will perform 



172 OS/MFT and OS/MVT TCAM Programmer's Guide 



different operations upon different types of messages, even when these different 
types are transmitted over the same Hne. Indeed, the user may in some cases be 
able to design a single Message Handler capable of processing all the messages 
that can be generated in a large TCAM-based telecommunications system per- 
forming a wide range of tasks. 

The path of a message through a Message Handler may be varied in two ways. 
One of these involves the use of control characters in the message header, and the 
other involves the setting of switches, based on the control characters, that 
determine whether a given subgroup is to be executed for the message. 

These switches, called path switches , are one-byte fields in the option table. The 
switches are initialized by an operand of the TERMINAL or TPROCESS macro 
and may subsequently be modified by a PATH macro or by a combination of 
OPTFIELD and DATOPFLD operator commands. An operand of a delimiter 
macro may specify that certain bits of a path switch are to be tested. If any of the 
specified bits are on, the subgroup introduced by the delimiter is executed; if none 
of the specified bits are on, control passes to the next subgroup. If a delimiter 
macro does not specify a path switch to be tested, its subgroup is executed uncon- 
ditionally. Different delimiters may test different sets of path switches. For an 
example of the use of path switches and the PATH macro to control the routing of 
messages from subgroup to subgroup, see the discussion of the PATH macro. 

By specifying, changing, and testing path switches, the user can determine which 
of the subgroups in an MH group are to be executed for a particular message. To 
control the path of a message within an inheader or outheader subgroup, the user 
may employ the MSGTYPE macro. The MSGTYPE macro compares a character 
or character string in the message header with a character or character string 
specified by a MSGTYPE operand. If the two characters or character strings 
match, the instructions between this MSGTYPE macro and the next MSGTYPE 
macro in the subgroup are executed (if this is the last MSGTYPE macro in the 
subgroup, all the remaining instructions in the subgroup are executed) and control 
is then passed to the next delimiter macro. If the two characters or character 
strings do not match, the instructions associated with this MSGTYPE macro are 
not executed, and control passes to the next MSGTYPE macro in this subgroup 
(or to the next delimiter, if this was the last MSGTYPE macro in the subgroup). 
A new comparison is made by each MSGTYPE macro to which control is passed. 
For an example of the use of the MSGTYPE macro to vary processing within a 
subgroup, see the description of the MSGTYPE macro. 

The PATH macro controls the routing of a message among subgroups. The 
MSGTYPE macro controls the path of a message within an inheader or outheader 
subgroup. 

Conditional Execution of Message Handler Functional Macros 

Several MH functional macro instructions may request conditional execution 
dependent upon the existence of a control field in the message. These macros are 
INITIATE, LOCK, MSGTYPE, PATH, PRIORITY, SCREEN, SETEOF, and 
UNLOCK, with the optional operand conchars. conchars may consist of from 
one to eight nonblank characters and may be specified in unf ramed character 
format or with framing C* ' or CLn' ' characters, or in hexadecimal format with 
framing X' ' or XLn' ' characters. 

These conditional characters specified in the macro are compared with the field in 
the message at the current location of the scan pointer. If the fields are identical. 



Designing the Message Handler 173 



the macro will be executed and the scan pointer will be advanced to the last 

character of the field. If the characters do not match, the scan pointer is not 

moved and the macro is not executed. If two or more macros in the same sub- ^ 

i 
group specify control character strings that are identical to a certain point but 

differ in length, and if there is any possibiHty that the same field in the message 

header will be checked for both strings, then these macros should be arranged 

according to decreasing length of their character strings. For example, if the user 

codes 

INITIATE 1 
LOCK 1 2 

in his inheader subgroup, both macros will execute if the field in the message 
header contains 112. However, if the field contains 12, only the INITIATE macro 
will execute. 

If the conditional characters are framed with CLn' ' or XLn' ' framing characters, 
n should agree with the actual count of characters. If n specifies a value greater 
than the actual count, it is possible that the macro may never be executed. For 
example, if a character string AB is defined as CL3*AB', the field is automatically 
padded to the right with a blank. If the BLANK = operand specifies 
BLANK=YES (or BLANK=X^40' or BLANK=C* '), a matching field can never 
be found. BLANK=YES states that blanks are not to be considered part of the 
character string when found in the header, but in this case the string used to 
determine execution contains a blank. 

In the case of multiple-buffer headers, the control characters must all be in the 
same buffer. The control characters may be entirely contained within the buffer I 

in which the scan pointer is located when the comparison is begun, or they may be % 
entirely contained within a subsequent buffer. They may not, however, be split 
between buffers. 

If the sequence 

MSGTYPE ABC 
MSGTYPE AB 
MSGTYPE A 

is coded by the user, and if the characters being checked are AB and these are the 
last two bytes in the buffer, the first MSGTYPE executes just as if three charac- 
ters were found but the compare was unequal. That is, the code following the first 
MSGTYPE is not executed and control passes to the second MSGTYPE macro. 
Execution of the second MSGTYPE finds two bytes, detects an equal compare, 
and passes control to the code following the second MSGTYPE. Note in this 
example that, even if a C is the next character beyond the AB in the message, the 
first MSGTYPE does not find the string because it is split between buffers. 

If the string ABC is the next string in the message and is located entirely within 
the next buffer, execution of the first MSGTYPE detects that no characters 
remain in the current buffer. Processing of buffer fields in this buffer is deferred, 
(including the subsequent MSGTYPE processing). When the next buffer is 
passed to the Message Handler, execution of the first MSGTYPE resumes at the 
start of data in this next buffer and, because the string ABC is found, control 
passes to the code following the first MSGTYPE macro. 



< 



174 OS/MFT and OS/MVT TCAM Programmer's Guide 



It is likely that the first result, where the string is split between buffers, is not the 
result desired by the user. To avoid such a result, either limit the header to a 
single buffer or avoid strings that are partially identical. 

User Code In A Message Handler 

The user may insert serially reusable assembler or macro-language code in a 
Message Handler to supplement the facilities provided by TCAM. User-written 
code can be included as either an open or closed subroutine. 

There are several reasons why the user might include such a subroutine. There 
may be no MH macro to process particular information he wishes included in his 
message headers. He may wish to expand the scope of an MH macro (for exam- 
ple, to correct an invalid destination field detected by the FORWARD macro). 
Or, he may wish to process a header field in a manner entirely different from that 
in which the MH macro handles fields of this type, for example, inserting a date 
having a format different from the one used by the DATETIME macro. 

General Requirements and Restrictions 

The following requirements and restrictions apply to both open and closed user- 
written subroutines that supplement the functions provided by TCAM macros in a 
Message Handler. 

1. All such subroutines must be serially reusable. 

2. No executable code should be included within an inmessage or outmessage 
subgroup, or between such subgroups. 

3. Branching from one Message Handler to another is not permitted. 

4. System macros that issue an SVC should be avoided, unless the user is fully 
aware of the implications of using such macros in the TCAM system. 

5. If the user provides a field or work area (as for the ERRORMSG, MSGGEN, 
and MSGEDIT macros), the field must be addressable by the MH. Such a field 
is addressable if placed after the OUTEND macro. If only one base register is 
used to establish addressability for the MH, the field must also be within 4096 
bytes of the STARTMH macro in order to be addressable. 

6. Nothing should be done that rehnquishes control. 

7. TCAM macros cannot be used in a closed subroutine. 

Multiple 'Buffer Header Considerations 

When the MH is handling messages having multiple-buffer headers, user code 
within the inheader and outheader subgroups should test register 1 5 for a negative 
return code before executing any open user subroutine or branching to a closed 
user subroutine, if the user subroutine to be executed depends upon certain data 
being in the buffer or upon the location of the scan pointer. A negative return 
code indicates that the previous TCAM macro needed the next buffer but it was 
not available (for an understanding of how this situation could arise, see 
Multiple- Buffer Header Handling in this chapter). If a negative return code is 
detected, a branch should be made around a user subroutine that depends upon 
the presence of certain data in the header, or upon the scan pointer; such a 
subroutine is eventually executed on header fields in a subsequent message 
segment. 

The USEREG= operand of the INTRO macro specifies the number of registers to 
be saved between header segments when user code is executed in an inheader or 
outheader subgroup that may handle multiple-buffer headers. The registers saved 
are sequentially ordered, beginning with general register 2. When the scan pointer 
comes to the end of a message segment and there is still code to be executed in the 



Designing the Message Handler 175 



inheader or outheader subgroup processing the segment, TCAM saves the address 
of the next (unexecuted) inheader or outheader instruction and also saves the 
contents of the registers specified by USEREG = . The segment continues through 
the subgroup, but macros that depend upon the location of the scan pointer or 
upon specific data being present in header fields do not execute for the segment. 
When the second segment is ready for handling, the STARTMH macro routes it 
directly to the inheader or outheader instruction whose address was saved, and 
restores the contents of the saved registers. (See Multiple- Buffer Header 
Handling for more information on this topic.) Only the contents of those user 
registers specified by USEREG= are saved and restored. 

Use of the USEREG= operand increases the size of the MCP. This operand 
should be coded only when an inheader or outheader subgroup that contains user 
code can expect to handle messages having multiple-buffer headers, with the user 
subroutine extending across buffers. 

The user can determine the number of extra bytes of main storage that coding 
USEREG= will require by applying the following formula: 

S=4R(L+T) 

where 

S is the number of extra bytes added to the MCP. 

R is the number of registers to be saved between buffers, as specified in the 
USEREG= operand of the INTRO macro. 

L is the number of lines in the system on which are located stations whose 
TERMINAL macros omit the BFDELAY= operand. 

T is the number of stations whose TERMINAL macros specify the 
BFDELAY= operand. 

Under certain error conditions, TCAM sends buffers that contain no data through 
the MH to execute the proper inmessage or outmessage subgroup. These buffers 
should be handled accordingly by any user code that depends upon data being in 
the buffer or upon the location of the scan pointer. See Using SETS CAN to 
Locate a Header Field for specific considerations. 

Including an Open Subroutine 

A user-written open subroutine consisting of one or more assembler language or 
system macro instructions may be included in-Hne in the inheader, inbuffer, 
outheader, and outbuffer subgroups of a Message Handler. TCAM macros may 
be included in an open subroutine. All registers except register 12 and 13 are 
immediately available for use in such a subroutine. If register 13 is used in the 
subroutine, its original contents must be saved and restored by the user. Register 
12 should not be changed by user code, since it is the base register. If more than 
one base register is used, the other base registers must also be preserved. 

When a user-written open subroutine is coded in an inheader or outheader sub- 
group that can handle messages having multiple -buffer headers, the contents of 
user registers will be lost if the header fields being processed by the user routine 
extend across more than one buffer. (To see why this is so, consider carefully the 
Multiple-Buffer Header Handling in this chapter.) The user may specify that the 



176 OS/MFT and OS/MVT TCAM Programmer's Guide 



contents of his registers be preserved in this case by suitably coding the 
USEREG= operand of the INTRO macro. When this operand is coded, the 
; contents of the user's registers are saved when the scan pointer reaches the end of 

the first segment of a message having a multiple-buffer header, and are restored to 
the user routine when the second segment arrives at the inheader or outheader 
subgroup. 

Including a Closed Subroutine 

A user-written closed subroutine may be included as a control section in the MCP. 
Access may be gained to such a subroutine by any Message Handler in the MCP, 
or as a result of an exit being taken that is specified by an INTRO, STARTMH, 
DCB, READY, ERRORMSG, or FORWARD macro. A closed subroutine 
cannot contain TCAM macros except MHGET and MHPUT. When activating a 
closed subroutine, the user must provide his own linkages; he should save and 
restore the invoking Message Handler's registers. Figure 19 illustrates the flow of 
control between an MH and a user-written closed subroutine, and presents the 
recommended linkages. 



Designing the Message Handler 177 



MHl 



(Dafa Set initialization macros) 
STARTMH 



(Other MH macros) 



CALLUSERRTN>- 
• (Next MH Macro) 






(USERRTN calls no other subroutine) 
-^ USERRTN CSECT 

USING *,15 
SAVE (14,12) 



(User G)de) 



<RETURN (14,12),T 
END 









(USERRTN 


calls another subroutine) 




"^ USERRTN 


CSECT 

USING M5 

B SKIP 




SAVEl 


DC ISF'O' 




SKIP 


SAVE (14,12) 
ST 13,SAVEH-4 
[A 12, SAVEl 
ST 12,8(13) 
LR 13,12 
DROP 15 
USING SAVEl, 13 

• 
(User Code) 

• 
L 13,4(13) 

—< RETURN (14,1 2), T 










END 



Figure 19. Activation of a Closed, User-Written Subroutine 



< 



178 OS/MFT and OS/MVT TCAM Programmer's Guide 



Using LOCOPT To Locate An Option Field 

The LOCOPT macro enables the user to obtain the address of any option field 
assigned to a particular station. The address of the desired field is placed in a 
user-specified register. A user-written routine may then examine and modify the 
contents of the option field. 

Using SETSCAN to Locate a Header Field 

The SETSCAN macro may be used to locate a portion of the message header for 
subsequent examination or processing by a user-written subroutine (but see 
Restriction #5 in the section General Requirements and Restrictions,) For a 
detailed description of the capabilities of SETSCAN, see the discussion of the 
macro. 

Note: Error buffers that contain no data should be handled accordingly by 
user code that depends upon data being in the buffer or upon the position of 
the scan pointer. If using the SETSCAN macro to locate a field for pro- 
cessing by user code, the user should recognize a buffer with no data by 
testing for a return code of XTC in register 15. If the return code X'FC is 
in register 15, the user code that depends upon data being in the buffer or 
upon the position of the scan pointer should be bypassed. 

Two capabiHties of SETSCAN are of particular interest with respect to user code: 

• By coding MOVE = RETURN, the user may employ SETSCAN to locate a 
designated character string in the header and to place the absolute main-storage 
address of the last character of the string in a specified register, to be used by 

; user code. When MOVE=RETURN is specified, the scan pointer is not 

^ actually moved, so the user need not worry about repositioning it. If this 

capabiUty is to be utilized effectively, the character string to be examined must 
be located entirely within a single buffer unit, because buffer units are not 
usually contiguous in main storage; consequently a long character string may be 
split between two units in different locations in main storage. If the character 
string to be processed is divided between two buffer units, and the user knows 
where in the string the division occurs, he may treat the segments as separate 
character strings, issue a SETSCAN macro specifying MOVE = RETURN to 
find the address of each, and process each independently. 

• SETSCAN may be used to determine the main-storage address of the header 
byte to which the scan pointer is currently pointing. This is done by specifying 
MOVE = RETURN and coding as the integer operand. If the user codes 

SETSCAN , MOVE=RETURN 

the address of the current location of the scan pointer is returned in register 15. 

Using MSGTYPE To Locate A Header Field 

User-written code may be included in inheader and outheader subgroups to 
interrogate and modify a field in a buffer of a message, and to interrogate but not 
modify a field that spans more than one buffer of a message header. 

The next field in a buffer, the one immediately following the scan pointer, can be 
obtained from the buffer by using a MSGTYPE macro that dehberately fails as 
follows: 



De signing the Me ssage Handler 179 



MSGTYPE C ' XXXXXXXX ' 
MSGTYPE 

Access to fields up to eight bytes in length can be gained by this method, the 
number of characters in the MSGTYPE operand is the length of the field. In this 
example, an eight-byte field is to be located. Care should be taken not to specify 
as the MSGTYPE operand any string that could be found in the header. If a 
matching string is found, the scan pointer is adjusted to point to its last byte. 

If the string sought extends across buffers, it cannot be modified. This can be 
determined by examining the contents of the second byte of the AVT parameter 
area lEDPARM, addressable throughout the MCP. If this byte is less than the 
requested length, the field spans buffers. The byte at lEDPARM+l is maintained 
in hexadecimal format. 

If the field does not span buffers, it may be modified by the use of the MSGEDIT 
macro. Insertions before the string, removal of the string, or removal and replace- 
ment of the string may be performed by coding an appropriate MSGEDIT macro 
with the AT operand specified as SCAN (see the discussion of the MSGEDIT 
macro in this chapter). Insertion after the string may be performed by coding a 
SETSCAN macro with a count equal to the length of the string, followed by the 
desired MSGEDIT macro. It is recommended that a MSGEDIT macro specifying 
the string itself as the AT operand not be used, since all occurrences of the string 
found, not merely the first one, will cause the MSGEDIT function to be per- 
formed. 



The following procedure allows the examination of a field that begins in one 
buffer and ends in a subsequent buffer (not necessarily the next buffer). It makes 
use of two parameters returned by the MSGTYPE function: ^ 

1. The characters found, whether matching or not, and whether as many as i 
requested or not, are placed in the AVT work area lEDDOUBL; 

2. The count of characters found is placed in the second byte of the AVT parame- 
ter area lEDPARM. 

The procedure may be varied depending on the length of the field to be examined. 
This example assumes the maximum, an eight-byte field. 



SPLIT 



LOOP 



SET INITIAL LENGTH DESIRED 
POINT TO EIRST BYTE 
OE WORK AREA 



TEST IF ANY BYTES FOUND 
BRANCH IF NOT TO AWAIT 
NEXT BER 

The operand of the MSGTYPE macro should specify the same number of characters 
as in the string desired, and the operand should be such that a match cannot be 
found. Because no match is found, the MSGTYPE macro branches to the next 
delimiter. Therefore, a delimiter must be specified as a branch address. In this case, 
MSGTYPE is used. 



MVI 


COUNT, 8 


LA 


RWORK,WORK 


CNOP 


0,4 


MSGTYPE 


C XXXXXXXX' 


MSGTYPE 




CLI 


IEDPARM+1 ,0 


BE 


NEXT 



SR 


REGA,REGA 


CLEAR REGISTER FOR 
INSERT 


IC 


REGA, COUNT 


PICK UP DESIRED 
COUNT DECREMENT 


BCTR 


REGA,0 


FOR EXECUTE 


EX 


REGA , MOVE 


MOVE BYTES FOUND 
TO WORKAREA 



i 



180 OS/MFT and OS/MVT TCAM Programmer's Guide 



LA 



CLC 

BE 



REGA, KREGA) 



RESTORE TRUE 
DESIRED COUNT 



These instructions move the characters found to the work area. The MVC 
instruction (MOVE) is executed by the EX instruction so that the target 
address of the MVC can be modified. 



C0UNT,IEDPARM+1 



FOUND 



ARE ALL DESIRED 
BYTES FOUND 
BRANCH IF YES 



The count field will be higher if not all the bytes are found. 



SR 
IC 
AR 



SR 



STC 



SCAN 

) 

* 

MOVE 
WORK 
COUNT 

FOUND 



STC 

SETSCAN 

B 



MVC 

DS 

EQU 



DS 



REGB,REGB 
REGB,IEDPARM+1 
RWORK , REGB 



CLEAR REGISTER 
FOR INSERT 
PICK UP NUMBER 
OF BYTES FOUND 
ADJUST WORK AREA 
ADDRESS 



The address register for the work area now points to the next byte to be 
filled, which will come from a subsequent buffer. 



REGA,REGB 


COMPUTE HOW 




MANY MORE 




BYTES NEEDED 


REGA, COUNT 


AND RESET 




LENGTH FIELD 


REGA,SCAN+7 


MODIFY SETSCAN 





PARAMETER LIST 


LOOP 


GO GET REMAINING 




BYTES 


0( 0,RWORK),IEDDOUBL 


EXECUTED MOVE 


CL8 


INSTRUCTION 


LOOP+ 1 1 




OH 


EXAMINE FIELD IN 




WORK 



The SETSCAN function moves the scan pointer to point to the last byte in the 
buffer. The skip length is adjusted to the proper number by modifying the parame- 
ter list. 

When the MSGTYPE function is executed again, the scan pointer is moved 
beyond the end of data in the buffer. The test following MSGTYPE must branch 
back to the next required buffer processing. Because of the setting of the scan 
pointer, that processing will not be performed on this buffer. 

When the next buffer is passed to the Message Handler, execution of the 
MSGTYPE function will be started again. At this time, the remaining bytes 
desired will usually be obtained. 

Note, however, that if the next buffer does not contain enough bytes to complete 
the count desired — if, for example, it contained only blanks — the buffer following 
it would be examined. That is, the field desired may actually be split over many 
buffers, and the procedure will still continue. 



Designing the Message Handler 181 



Using the FARM Parameter of the EXEC Job Control Statement 

The user may wish to pass information to his user code by means of the FARM 
parameter of the EXEC job control statement (this capability is described in the 
OS publication Job Control Language . If the PAR1VI= operand is specified, 
when control is passed to TCAM register ! contains the address of a fullword, the 
low-order three bytes of which contain the address of a two-byte length field 
immediately followed by the data specified in the FARM parameter. INTRO 
stores the contents of register 1 in a fullword on a fullword boundary, from which 
it may be retrieved by user code. The name of the fullword is lEDSPLPT. The 
address in register 1 is then overlaid. 

Message-Handler Macro Return Codes 

During execution, certain MH macros cause a return code to be placed in a 
general register, usually register 15. The table below lists those TCAM macros 
whose return codes may be checked by user code in a Message Handler. The 
return code occupies the low-order byte in the register indicated; the rest of the 
register usually contains all zeros. Return codes of X'FC are negative return 
codes; the high-order three bytes of the register contain binary ones. Some 
macros also return an address in a register; the locations and nature of such 
addresses are also indicated in the following table. 







Return 


Macro 


Register 


Code 


COMMBUF 


15 


X'OO' 




15 


X'04' 



15 



15 



X'08' 



X'OC 



Meaning 

Good return 

Data area too small; macro did not 

execute. (The data area 

size specified in the COMMBUF= 

operand of the INTRO macro is 

too small). 

MAXDEEP value exceeded. 

(register 1 will contain the 

number of times MAXDEEP was 

exceeded). 

LIST= operand specified 

a name which was not 

a TLIST entry. 



I 



COUNTER 


15 


X'OO' 


Good return 




15 


X'FF' 


Option field not found 


CTBFORM 


15 


X'04' 


Separator character insertion 
requested; none defined. 




15 


X'08' 


Insertion of opfield data 
requested; option field not 
found. 




15 


X'OC 


Combination of X'04' and 
X'08'. 




15 


X'lO' 


Insertion of device id requested; 
device id not defined. 




15 


X'14' 


Combination of X'04' and X'lO 




15 


X'18' 


Combination of X'08' and X'lO 




15 


X'lC 


Combination of X'04', X'08', 
and X'lO' 



( 



1 8 2 OS/MFT and OS/M VT TCAM Programmer's Guide 



15 



X'20' Requested insertion of device 

id and option field; not done 
(out of units). 



DATETIME 


15 


X'OO' 


Good return 




15 


X'04' 


Insufficient reserve characters 


FORWARD 


15 


X'OO' 


Good return 




15 


X'04' 


Invalid destination 


LOCK 


15 


X'OO' 


Good return 




15 


X'04' 


Destination not specified 




15 


X'08' 


Destination not a process entry 


LOCOPT 








a) if return 


15 


Address 


Good return 


requested in 




of 




R15 




option 
field. 






15 


X'OO' 


Option field not found 


b) if return 


15 


X'OO' 




requested 


USEREG 


Address 


Good return 


in user- 




of 




specified 




option 




register 




field. 




(USEREG) 


15 


X'04' 






USEREG 


Un- 
changed 


Option field not found 


LOG 


15 


X'OO' 


Good return 




15 


X'04' 


DCB or LOGTYPE entry named 
in macro not found 


MHGET 


15 


X'OO' 


MHGET successful; no errors. 




15 


X'04' 


Data moved; work area too 
small; data truncated. 




15 


X'08' 


TCAM not in system. 




15 


X'OC' 


Empty buffer; no user processing 
permitted. 


MHPUT 


15 


X'OO' 


MHPUT successful. 




15 


X'04' 


MHPUT could not allocate enoug 



15 


X'08' 


15 


X'lO' 


15 


X'OC 



units; data is truncated. 

This return code is also 

set when the number of 

units per buffer has 

reached maximum. 

TCAM not in the system. 

Length of work area not initialized. 

Reserves specified are too large; 

data was moved. 



Designing the Message Handler 183 



Macro 
MSGEDIT 



Register 

15 
15 



Return 
Code 

X'OO' 
X'04' 



Meaning 

Good return 

No units available 



MSGLIMIT 15 

15 



ORIGIN 



15 
15 

15 

15 



QACTION 


15 


SCREEN 


15 


(2260) 


15 




15 


SCREEN 


15 


(3270) 


15 




15 




15 



X'OO' Good return 

X*04' Option field not found 

X^OO' Good return. The ORIGIN macro 

executed successfully. 

X'04' Invalid origin. The FORM= operand 

was specified and the source 
terminal was not valid. 

X*08' The FORM= operand was specified, 

but the source terminal is not 
in the concentrator network. 

X*OC' The FORM= operand was specified, 

but the origin specified in the 
message is not a valid name or ID 
for a terminal attached to the 
concentrator entering d^ta (the 
first terminal entry following 
the entry for the concentrator 
is assumed to be the origin). 

X'08' No buffers available. 

X'OO' Function not done. 

Function Good return 

Byte 

X*04' Invalid operation for 2260 

X*00' Function done. 

X'04' Invalid operation for 3270. 

X'08' Invalid buffer data stream. 

X'OC Command code not found or 

invalid use of EAU, WDC, or 

WRE. 



SEQUENCE 




a) macro 


15 


issued in 


15 


inheader 


15 


subgroup 


15 


b) macro 


15 


issued in 


15 


outheader 




subgroup 




SETEOM 


15 




15 




15 



X^OO' 
X^04' 
X^OS' 

X'OO' 
X'04' 



X'04' 
X'OS' 
X'OC 



Good return 

Sequence number in message high 

Sequence number in message low 

Originating station unknown 

Good return 

Insufficient reserve characters 



EOM delimiter used 
Delimited by user-specified length 
Delimited by EOM and user- 
specified length 



i 



184 OS/MFT and OS/MVT TCAM Programmer's Guide 



Macro 

SETSCAN 

al) locate 

specified 

character 

string 

and return 

address in 

R15 

a2) locate 
specified 
character 
string 
and return 
address 
in user- 
specified 
register 
(USEREG) 



bl) skip 

n characters 

and return 

address 

inR15 



b2) skip 
n characters 
and return 
address 
in 

user- 
specified 
register 
(USEREG) 

c) skip 

n characters 

backward 



d) locate 
scan pointer 
address 



TGOTO 



Register 
15 

15 
15 
15 
USEREG 



15 
USEREG 

15 
USEREG 



15 



15 



15 
USEREG 



15 
USEREG 



15 
15 



15 

15 
15 



Return 
Code 



Address 
of last 
character 
in string. 
X'OO' 

XTC 

X'OO' 

Address 
of last 
character 
in string 
X'04' 
Un- 

changed 
XTC 
Un- 
changed) 

Address 
of 

character 
skipped to 
X'OO' 



X'OO' 
Address 
of 

character 
skipped 
to 

X'04' 
Un- 
changed 

X'OO' 
X'04' 



Address 
of scan 
pointer 
X'FC 

X'04' 



Meaning 



Good return 



Specified character string not 

found in this buffer 

Scan pointer beyond end of buffer. 

Good return 



Specified character string 
not found in this buffer 

Scan pointer beyond end of buffer. 



Good return 



n greater than the number of 
characters remaining in this buffer 



Good return 



n greater than the number of 
characters remaining in this 
buffer 

Good return 

n greater than the number of 
characters preceding the scan 
pointer in this buffer 

Good return 



Scan pointer beyond end of buffer. 

The terminal that entered this 
message either is not attached to a 
concentrator, or is attached but the 



Designing the Message Handler 185 



Message Translation 



station's TERMINAL macro does 
specify LMD=YES or MB=YES. Pro- 
cessing continued in the inmessage 
subgroup of the first MH. 

15 X'08 ' The TGOTO macro specified that the 

name of the second MH for the 
terminal entering the message was 
in an option field, but the option 
field was not initiaUzed by the 
OPDATA= operand of the station's 
TERMINAL macro. 

1 5 X'OC The address of the second MH, 

specified either in the TGOTO 
macro or in an option field, 
is not a valid MH address. 

Note: All macros give an error return code if a zero-length buffer 
(see Glossary) is passed through the message handler. 



TCAM provides a facihty for translating incoming messages from Une code into 
EBCDIC and for translating outgoing messages from EBCDIC to line code. 
Translation is specified by issuing a CODE macro in the incoming and outgoing 
groups of an MH. 

The user who does any appreciable amount of header analysis, or whose system 
includes stations using different Hne codes, will probably want to use TCAM's ^ 

translation facility. Incoming translation must be specified for lines over which ^ 
operator commands may be entered, since the CODE macro is used by TCAM to 
check for such messages (see the discussion of the CODE macro for a way of 
selectively translating operator commands while leaving other messages entered 
on the same hne untranslated). 

Translation is not required in a message-switching application for which httle or 
no header analysis is required, provided that the originating and destination 
stations are of the same type. The careful user may be able to avoid translating in 
other situations. The operands of most MH macros may be specified in hexadeci- 
mal format. By using the tables and information located in Appendix G , the user 
may enter in his MH macro operands the hexadecimal representation of header 
fields that are in line code and thereby avoid having to translate. The user seeking 
to avoid translation should remember that the names entered in the terminal table 
(that is, the names given to the TERMINAL, TLIST, TPROCESS and LOGTYPE 
macros) must be specified in EBCDIC characters; no hexadecimal capabihty is 
provided for specifying these names. 

The user may avoid translation of messages handled by a particular incoming or 
outgoing group of a Message Handler by omitting the CODE macro from that 
group. The user may avoid translation of messages received from or sent to the 
Hues in a certain Une group by coding a CODE macro having no operand and by 
specifying TRANS =EBCD in the line group DCB macro for the Une group. 



Translation is usually accompUshed by using tables provided by TCAM, although 
the user may provide his own translation tables if he wishes. The user providing 
his own tables should format the individual 256-byte tables as described in the 



i 



1 86 OS/MFT and OS/M VT TCAM Programmer's Guide 



example illustrating the use of the TRANSLATE instruction in the OS publication 
Principles of Operation . A user-defined translation table should consist of a 
, fullword on a fullword boundary, followed by a 256-byte table for translating 

from Une code to EBCDIC, which is followed in turn by a 256-byte table for 
translating from EBCDIC to line code. The initial word should contain the 
address of the first byte of the second table. The control section containing the 
user-written translation table must be included at link edit time for the MCP. 

Translation tables are provided for all stations supported by TCAM. The names 
of these tables are given in the following list. When one of these names, or the 
name of a user-specified table, is coded as part of the TRANS = operand of the 
line group DCB macro, incoming messages for this hne group are translated from 
the specified line code to EBCDIC; outgoing messages are translated from 
EBCDIC to the line code, when CODE macros are executed in the incoming and 
outgoing groups of the MH for the line group. The table specified by the DCB 
operand can be changed for messages to or from a particular line, station, or 
application program by entering a different table name in the tablename operand 
of the CODE macro and by using MSGTYPE macros or path switches to cause 
different CODE macros to be executed for different messages (see Variable 
Processing within a Message Handler in this chapter). 

All of the characters in the character sets of each of the types of station supported 
by TCAM can be represented within the computer. However, some characters 
valid for one type of station may not be valid for another type, and some charac- 
ters valid for a station may have no EBCDIC equivalents. The way in which 
TCAM handles these problems is described in the sections Nonequivalent 
Characters and Substitutions in Appendix D. Internal and Transmission code 
^ Charts . 

►■' 

See Appendix G. Device- Dependent Considerations , for specific information 
about the character sets for the: 

• 1050 Data Communication System; 

• 2260 Display System; 

• 2740 Communications Terminal; 

• TWX stations; 

• WTTA terminals. 

Names of Code Translation Tables Provided by TCAM 

Table Name Type of Conversion Terminal 

1030 1030 code to EBCDIC and back IBM 1030 

1050 1050 code to EBCDIC and back IBM 1 050 

105F 1050 code to EBCDIC and back; IBM 1050 

converts incoming lowercase 
letters to uppercase 

1 060 1 060 code to EBCDIC and back IBM 1 060 

2260 2260 code to EBCDIC and back IBM 2260 

2265 2265 code to EBCDIC and back IBM 2265 

2740 2740 code to EBCDIC and back IBM 2740 



Designing the Message Handler 187 



Table Name 
274F 

BC41 
EB41 
CR41 

ITA2 

ZSC3 



Type of Conversion 

21 AQ code to EBCDIC and back; 
converts incoming lowercase 
letters to uppercase 

2741 BCD to EBCDIC and back 

2741 EBCDIC to EBCDIC and back 

2741 Correspondence Code to EBCDIC 
and back 

5-level International Telegraph 
Alphabet No. 2 to EBCDIC and back 

5-level Figure Protected Code 
ZSC3 to EBCDIC and back 



Terminal 
IBM 2740 

IBM 2741 
IBM 2741 
IBM 2741 

WTTA 

WTTA 



TTYA 



TTYB 



TTYC 



6BIT 
ASCI 



EBCD 



5-level (Baudot) code to EBCDIC 


AT&T 


and back 


83B3, 




WU115A 


8-level TWX code to EBCDIC and back 


AT&T 




33/35 




TWX 




(parity) 

AT&T ^ 


8-level TWX code to EBCDIC and back 




33/35 




TWX 




(non- 




parity) 


6-bit Transcode to EBCDIC and back 


IBM 2780 


ASCII to EBCDIC and back 


IBM 2770, 




2780, 3270, 




3670,3735, 




S/360, Model 20 


No translation; coded for stations 


IBM 1130, 


using EBCDIC transmission code, 


2770, 2780, 


and when no translation is 


2790, 3270, 


desired. 


3670,3735, 




3780, S/360, 




Model 20 



i 



188 OS/MFT and OS/MVT TCAM Programmer's Guide 



Using TCAM's Hold/Release Facility to Protect Outgoing Messages from Loss 

TCAM can temporarily suspend transmission of outgoing messages to a station. 
Transmission may be suspended either for a specified period of time or until the 
user chooses to resume outgoing traffic. Messages may be held either by the 
HOLD macro or by the operator command SUSPXMIT, and released by the 
RESMXMIT operator command, by the MRELEASE macro issued in an applica- 
tion program, or automatically at the expiration of the time interval specified by 
the HOLD macro. 

HOLD maybe used to defer transmission of messages that should not be sent 
immediately because of error conditions at the destination station (the destination 
is the station for the message being processed by the outmessage subgroup when 
HOLD executes). If the macro is not used, messages that cannot be transmitted 
because the destination is temporarily out of order are treated as if they have been 
transmitted, even though they do not reach their destinations. 

Once HOLD executes in an outmessage subgroup, no messages are sent to the 
destination station either until the interval specified as an operand of the macro 
expires, or until a RESMXMIT operator command or an MRELEASE application 
program macro is issued. Accumulated messages can be released by RESMXMIT 
or MRELEASE even though the specified time interval has not elapsed. 

HOLD can be either unconditional or conditional based upon the setting of the 
message error record. HOLD until a release is issued can be used if a station 
unexpectedly fails. The error situation might be detected by a HOLD macro 
based on the message error record. The interval format can be used if a station in 
1) the system is scheduled for maintenance for a specific period of time. In this case, 

an unconditional HOLD with the INTVL= operand might be used. 

The HOLD macro cannot be executed for a station supported by main-storage- 
only queues or for a station whose line is not open or has been opened idle. The 
operator command SUSPXMIT, which also causes an intercept, cannot be used 
unless a HOLD macro has been coded somewhere in the Message Handlers. If 
the operator control hold facility alone is required, the HOLD macro coded in an 
MH can specify an impossible combination of errors in the mask associated with 
the message error record. This will ensure that the macro is never executed and 
will provide the operator control capability. 

In addition to its function of protecting outgoing messages from loss, HOLD also 
may be used to achieve an inquiry/response capability, which is discussed in 
TCAM 's Inquiry /Response Facilities in the section Writing TCAM-Compatible 
Application Programs . 

Coding the Message Handler for an Application Program 

The user may code a special Message Handler for his application program, or he 
may include subgroups for his application program in an MH assigned to a line 
group. In the latter case, he must use variable routing through the MH, as dis- 
cussed in this chapter, to ensure that the application-program-related subgroups 
are executed only for messages being sent to or received from an application 
program. The PCB macro for an application program specifies the MH that 
handles messages to or from that application program. 



Designing the Message Handler 189 



Design Steps 



Do not code an outmessage subgroup in an MH handling messages destined for an 
application program; functional macros that appear in such a subgroup do not 
execute. An OUTMSG delimiter macro is not necessary since the OUTEND | 

macro provides any required TCAM functions in the absence of OUTMSG. 

If any messages are to be entered by the application program an incoming group is 
required. The incoming group must contain a FORWARD macro. 

The following MH functional macros should not be coded in subgroups handling 
messages being sent to or received from an application program: CUTOFF, 
LOCK, UNLOCK, MSGFORM, MSGGEN, MSGLIMIT, INITIATE, and 
SCREEN. 



The design of a Message Handler and related control areas is complex because of 
the large number of functions available in TCAM and the variety of requirements 
of different installations. The following general outline suggests a possible 
approach. 

1 . Define the requirements of the application. Are messages to contain both 
header and text segments? Is an application program involved? How many 
characters will be in a normal message and in the longest message? Optimum 
buffer size depends on this. 

2. Refer to the table of MH functions and macros defining the functions in a 
previous section of this chapter and the related text to determine which func- 
tional macro instructions might be used in the application. Study the detailed 
descriptions of these macros. Tentatively select those macros that provide the 

desired functions. # 

3. Design the message header, if applicable. Are the following fields % 
necessary — origin, date, time, destination (single or multiple), priority? Should 
the field be entered by the terminal operator or inserted by the Message Han- 
dler? What should the program EOA characters be? 

4. Start from a minimum Message Handler (required delimiter macros) and add 
the macros necessary to process the header. 

5. Determine what validity checking is required and add the appropriate macro 
instructions. 

6. Determine what error conditions need to be tested for and handled. 

7. Determine what supplementary functions are desired — logging, initiate han- 
dling, message limit, etc. 

8. Assemble the completed MCP and take a look at it before linkage editing. 

No attempt should be made to write a Message Control Program in one step. A 
program should first be written, assembled, and tested that provides a very few of 
the desired functions. Other functions may be added as famiharity with the 
TCAM facilities grows and as the simpler programs are run successfully. For 
example, in a message switching application, a first program might include only 
the delimiter macros and the ORIGIN, SEQUENCE, CODE, and FORWARD 
functions. A second step might add the block checking function of the 
STARTMH macro, DATETIME, and some ERRORMSG functions. A third step 
might add multiple destinations, message counting and logging, and additional 
error handling. A final step could add the MSGTYPE or PATH functions to 
handle different message types. 

The order in which macro instructions are specified requires thoughtful planning, g 
It is important that some macro instructions be specified early enough in a sub- ^ 
group so that they act on the first header buffer; these macro instructions are 



190 OS/MFT and OS/MVT TCAM Programmer's Guide 



CODE, FORWARD, PRIORITY, and INITIATE (and PATH if all segments of 
the message are to be handled alike). In determining the relative placement of 
macros within the subgroup, the use of the scan pointer must be understood. 
(Note the sample Message Control Programs in the chapter Putting the MCP 
Together .) 

Delimiter Macro Instructions 

Delimiter macro instructions identify the beginning or the end of various groups 
and subgroups of a Message Handler. They also provide initiahzation 
(addressability) and control functions within an MH. In the table below are the 
various groups and subgroups and the delimiter macro instructions that control 
their execution. 

The STARTMH macro identifies the beginning of an MH and must be the first 
instruction in every MH. TCAM provides initiahzation by setting up base regis- 
ters and addresses for an MH at this point. STARTMH code determines whether 
the message being processed is incoming or outgoing and directs the segment to 
the incoming or outgoing group accordingly. STARTMH handles end-of-block 
checking, if specified. 

STARTMH is the only delimiter macro that is always required. If the MH is to 
handle incoming messages, the INHDR, INEND, and OUTEND delimiter macros 
are required. If the MH is to handle outgoing messages, the OUTEND macro is 
required. Each of the remaining delimiters is required only if the user chooses to 
include in the MH the functional macros associated with that delimiter. 

If an incoming group is present, an inheader subgroup (or an inblock subgroup 
followed by an inheader subgroup) must be the first subgroup. An outheader 
subgroup may be specified before or after an outbuffer subgroup (if both are 
present). INEND and OUTEND identify the ends of the incoming and outgoing 
groups respectively. 

If an MCP contains more than one MH, a LTORG instruction (described in the 
OS pubUcation Assembler Language) should be coded immediately after the last 
delimiter macro (INEND or OUTEND) of each MH if in-Une user code includes 
literals. 



Designing the Message Handler 191 



MH Groups, Subgroups, and Delimiter Macro Instructions 



Message Handler 


Group 


Subgroup 


Delimiter Macro 






STARTMH 






INCOMING 
GROUP 


INBLOCK 
SUBGROUP 


INBLOCK 




INHEADER 
SUBGROUP 


INHDR 


INBUFFER 
SUBGROUP 


INBUF 


INMESSAGE 
SUBGROUP 


INMSG 






INEND 










OUTGOING 
GROUP 


OUTHEADER 
SUBGROUP 


OUTHDR 




OUTBUFFER 
SUBGROUP 


OUTBUF 


OUTMESSAGE 
SUBGROUP 


OUTMSG 






OUTEND 













i 



192 OS/MFT and OS/MVT TCAM Programmer's Guide 



STARTMH 



The STARTMH macro 

• establishes addressability for an MH; 

• directs messages to an incoming or outgoing group, as appropriate; 

• specifies whether logical messages are defined; 

• specifies whether line-control characters are to be left in messages; 

• checks for occurrence of hardware errors during message transmission; 

• handles user-detected logical errors; 

• specifies whether tete-a-tete interaction may occur between the computer and a 
station; 

• specifies whether end-of-block completion handling is to be used; 

• is required as the first macro in every MH. 

STARTMH is required and must be the first macro instruction of every MH. This 
macro causes EOB checking to be performed. If a recoverable error is detected 
and no part of the block has been sent through the MH, retries are performed for 
receive operations (regardless of what STARTMH operands may specify). How- 
ever, if part of the block has been sent through the MH when a recoverable error 
is detected, EOB checking requires that the STOP=, CONT=, CONV=, or 
LOGICAL= operand be specified. Basically, this checking consists of determin- 
ing whenever an EOB, ETB, ETX, or EOT control character is received, whether 
certain types of transmission and user-specified logical errors have occurred; if so, 
the message is disposed of according to certain operands specified in STARTMH. 

For an incoming message, EOB checking occurs before a buffer containing an 
EOB is processed by the MH. If a hardware error is detected and retry is possible, 
a retry operation is performed (see the Glossary for a definition of retry). No 
message handUng occurs until the block is received again. If retry is not possible 
(because, for instance, the retry count is exhausted), either the error is ignored 
and the channel program is restarted to receive the next block, or transmission is 
terminated and the buffer continues through the MH, which processes it as the 
last buffer of the message. 

A buffer containing an incoming message segment is passed to the appropriate 
subgroup after EOB checking (if any), and when it is full. Depending upon how 
the user has coded the PCI= operand of the Une group DCB macro, and upon 
whether or not his incoming message contains EOB, ETB, or ETX control charac- 
ters, the buffer may be deallocated and passed to the appropriate MH subgroup 
soon after it is filled, or it may not be passed to the appropriate subgroup until 
transmission has ceased on the line; the latter case assumes there were no control 
characters in the incoming message. (See Dynamic and Static Buffer Allocation 
in the chapter Defining Buffers ). A full buffer is deallocated whenever a 
program-controlled interruption occurs; if PCI=N is specified, deallocation occurs 
when an EOB, ETB, or ETX control character is received (if there are no such 
characters, deallocation of buffers occurs after the transmission is completed). 

For outgoing messages, EOB checking (if specified) is performed after each block 
is transmitted. No check is made for logical errors. The transmission of a particu- 
lar block is deemed successful if the receiving terminal acknowledges that it has 
successfully received the block. Transmission errors detected by the terminal 
result in retries. Once the retry count is exhausted, transmission is either termi- 
nated or allowed to continue, as for incoming messages. After transmission has 



Designing the Message Handler 193 



terminated, control passes to the outmessage subgroup, whose macros may then 
check the message error record for the message and take appropriate action. 

See Appendix G. Device-Dependent Considerations , for specific coding informa- 
tion concerning the 1030 Data Collection System, the 1060 Data Communication 
System, the 2770 Data Communication System, and the 2780 Data Transmission 
Terminal. 



If the user specifies dynamic buffer deallocation by the PCI= operand of the line 
group DCB macro, and if the block size for his incoming messages is greater than 
his buffer size for incoming messages, segments containing transmission errors 
may be processed by the inheader and inbuffer subgroups of the MH before the 
EOB-checking routine detects the errors. Jn this case, when the EOB-checking 
routine detects the errors, segments in this block that have been enqueued are 
dequeued or ignored, and the input sequence number is decremented if it was 
incremented by a canceled segment. Dequeuing and sequence-number adjustment 
are done automatically by TCAM. However, any option fields that were updated 
on the basis of data in the canceled segments remain updated, and if the canceled 
segments were logged they remain on the logging medium. 

When the INITIATE macro is executed in the inheader subgroup handUng an 
incoming message, EOB checking is performed for that message, but there are no 
retries on the receive side (TCAM assumes an EOT condition when an error is 
detected on the receive side). 



Name 



Operation 



Operand 



mhname 



STARTMH 



LC= JOUTJ 

"(stop ] (YES 

_(cONt) ((opfield.switch) 

(YES 
,CONV=<' (opfield,switch) \ 
I NO 

,LOGICAL= \ (opfield) 

1 (opfieldl ,switch,opfield2) 

3REG= { integer [ 



,LMD= rVES 

^ (opfield,switch) 
( NO 



mhname 



Function: Name of the macro and of the Message Handler. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



i 



194 OS/MFT and OS/MVT TCAM Programmer's Guide 



LC= jIN \ 
|0UTj 



STOP= (yes 



I (opfield,switch) 



Notes: Must be the same as mhname specified in the MH= operand of the DCB 
for the Une group that uses this Message Handler. 



Function: Specifies whether Une-control characters in a start-stop message or in a 
BSC message in nontransparent mode are to be removed. 
Default: None. This operand must be specified. 
Format: IN or OUT. 

Notes: OUT causes TCAM to remove EOA and EOB Hne-control characters 
from incoming messages entered at a start-stop station, and to remove STX, ETX, 
SOH, and ETB Une-control characters from incoming messages entered at a BSC 
station. EOT Une-control characters are not removed when OUT is specified. 
EOB and ETB line-control characters are not removed when CONV=YES is 
specified, regardless of how LC= is coded. Line-control characters are not 
removed until after the message segment is in a buffer; therefore, the buffer must 
be large enough to accomodate Une control. 

The ITB control character is not considered by TCAM to be a line-control 
character and is not removed when OUT is specified. 

IN causes the line control to remain in incoming messages (unless such messages 
are in transparent mode, in which case "real" Une-control characters are removed 
regardless of how this operand is coded). 



Function: When a message block is found to be in error, this operand 
(conditionally) specifies that once the retry count is exhausted, transmission of 
this message is to be terminated. The error may be a hardware error or may be a 
user-detected logical error if the LOGICAL= operand is also specified. 
Default: None. Specification optional. 

Format: YES or (opfield,switch). op field must conform to the rules for assem- 
bler language symbols, and must be the name of a one-byte option field defined 
by an OPTION macro, switch may be either decimal or hexadecimal. If hexade- 
cimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that transmission is to be terminated unconditionaUy. 
(opfield^switch) specifies that transmission is to be terminated if any of the bits on 
in the switch are also on in the option field. 

When transmission is terminated because of an error detected by EOB checking, 
that portion of the message that has been received (or sent) continues through the 
incoming (or outgoing) group of the MH, where it is treated as if it were a com- 
plete message. The user may issue certain error-handling macros in the inmessage 
(or outmessage) subgroup of the MH that test bit 25 of the message error record 
and dispose of the message according to his specifications if bit 25 (which indi- 
cates that an error occurred during transmission of data) is on. If this operand is 
omitted, end-of -block checking is not done. 



Designing the Message Handler 195 



CONT= 



^YES ) 

] (opfield,switch) ) 



CONV= ( YES 

< (opfield,switch) 
(NO 



Function: When a message block is found to be in error, this operand 
(conditionally) specifies that once the retry count is exhausted, transmission of 
this message is to be continued. 
Default: None. Specification optional. 

Format: YES or (opfield,switch). opfield must conform to the rules for assem- 
bler language symbols, and must be the name of a one-byte option field defined 
by an OPTION macro, switch may be either decimal or hexadecimal. If hexade- 
cimal format is used, framing X* * characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that transmission is to continue unconditionally. 
(opfieldySwitch) specifies that transmission is to continue if any of the bits on in 
the switch are also on in the option field. 

When an error occurs, a bit in the message error record is set on. Message seg- 
ments are sent to the appropriate MH group as if no EOB error had been found. 
If this operand is omitted, end-of-block checking is not done. 



Function: Specifies whether EOB completion handling is to be used for the 
station, and (in conjunction with a LOCK macro) whether tete-a-tete interaction 
is in effect for the station. 
Default: CONV=NO 

Format: YES or NO or (opfield,switch). opfield must conform to the rules for \ 
assembler language symbols, and must be the name of a one-byte option field 
defined by an OPTION macro, switch may be either decimal or hexadecimal. If 
hexadecimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that tete-a-tete interaction is to be used unconditionally, 
and that a logical block of data being entered by a station is to be treated by 
TCAM as if it were a complete message. 

NO specifies that tete-a-tete interaction and EOB-completion handling are not to 
be used. 

(opfield.switch) specifies that tete-a-tete interaction and EOB-completion handling 
are to be used if any of the bits on in the switch are also on in the option field. If 
the path-switch setting is to be changed for this message, the first buffer must not 
contain an EOB if a change in EOB-completion handhng is desired for this 
message. If an EOB appears in the first buffer of this message, the next message 
will be the first message affected by the change. 

If the CONV= operand is specified, STOP= or CONT= must also be specified. 
If LMD= is coded with the (opfield, switch) option, CONV= can not use the 
(opfield,switch) option. For an explanation of tete-a-tete interaction, see 
TCAM's Inquiry /Response Facilities in Writing TCAM-Compatible Application 
Programs, 



{ 



196 OS/MFT and OS/MVT TCAM Programmer's Guide 



LOGICAL= ( (opfield) \ 

(^ (opfield l,switch,opfield2)j 

Function: Specifies whether a user-written routine is to be given control 
(conditionally) to test for logical errors (such as formatting errors in a card or an 
inquiry addressed to the wrong application program) in incoming messages on a 
block-by-block basis. 
Default: None. Specification optional. 

Format: (opfield) or (opfield I, switch,opfield2). opfieldl md opfield2 must 
conform to the rules for assembler language symbols, and must be the names of 
option fields defined by OPTION macros, switch may be either decimal or 
hexadecimal. If hexadecimal format is used, framing X' ' characters must be 
specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: (opfield) specifies that a user-written routine is to be given control uncon- 
ditionally, opfield refers to a four-byte option field, the high-order byte of which 
indicates that an error has been found. The low-order three bytes are the address 
of the routine to be given control, (opfield fswitch,opfield2) specifies that the 
user-written routine specified in opfield I is to be given control conditionally if 
any of the bits on in switch are also on in the one-byte opfield! . 

If this operand is specified, STOP= or CONT= must also be specified. The user 
may initialize the routine name, option field by coding a V-type address constant 
naming his routine as part of the OPDATA= operand of the TERMINAL or 
TPROCESS macro. Upon return from the user routine, STARTMH examines the 
high-order byte of the field. If the byte is not zero and if the STOP= operand 
specifies that transmission is to be terminated, transmission is terminated. If the 
byte is zero, or if the CONT= operand is in effect, operations are restarted on the 
line. If the byte is X'04' and the STOP= operand does not specify that transmis- 
sion be terminated, TCAM will send a Reverse Interrupt (RVI) control sequence 
on a BSC line instead of the positive reply to the previous text block. (For 
additional information on RVI see the pubUcation General Information-Binary 
Synchronous Communications , GA27-3004.) This capability allows the user to 
interrupt the receipt of blocks from terminals on a BSC Hne and to send a high- 
priority message over that line. The user codes LOGIC AL= (opfield) on the 
STARTMH macro. The routine pointed to by the low-order, three bytes of the 
option field will execute an instruction that will set the high-order byte of the 
option field to X'04', if the user desires this capability. 

The user routine must save and restore registers 2 through 12, and must not alter 
the contents of register 13 and 14. On entry to the user routine the following 
registers contain: 

Register 1 — address of the four-byte option field containing the one-byte error 
indicator followed by the address of the user routine. 

Register 4 — address of the LCB (line control block), an internal TCAM control 
area described in the TCAM PLM . 

Register 6 — address of the last buffer in the block of the data (the buffer con- 
taining the EOB); this is the only buffer in this block that may be tested for 
logical errors by the user routine. 

Register 8 — address of the SCB (station control block), an internal TCAM 
control area described in the TCAM PLM . 



Designing the Message Handler 197 



Register 13 — address of a TCAM save area; must not be altered. 
Register 14 — return address for the calling routine; must not be altered. 
Register 15 — address of the entry point for the user routine. 



( int 



BREG= ( integer^ 



Function: Specifies the number of base registers desired for this MH. 

Default: BREG=1 

Format: An unframed decimal integer between 1 and 11. 

Maximum: 1 1 

Notes: One base register is required for each 4096 bytes in the MH. Assignment 

begins with register 12 and works back to 0. If BREG=3 is coded, for instance, 

registers 12, 1 1 and 10 are assigned as the base registers for the first three 4096- 

byte blocks of this Message Handler. 



L!V1D=(^YES 1 

< (opfield, switch) , 

Ino 



Function: Specifies whether this MH is to handle logical messages. 
Default: LMD=NO 

Format: YES NO or (opfield,switch), opfield must conform to the rules for 
assembler language symbols, and must be the name of a one-byte option field 
defined by an OPTION macro, switch may be either decimal or hexadecimal. If 
hexadecimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that this MH is to be used solely for handling logical mes- 
sages. If NO is specified, or if this operand is omitted, this MH is to handle each 
physical transmission as a message (without defining logical messages with the 
SETEOM macro). ( opfield,switch ) specifies that tete-a-tete interaction and 
EOB-completion handling are to be used if any of the bits on in the switch are 
also on in the option field. If the path-switch setting is to be changed for this 
message, the first buffer must not contain an EOB if a change in EOB-completion 
handhng is desired for this message. If an EOB appears in the first buffer of this 
message, the next message will be the first message affected by the change. 
LMD=YES must be coded if this MH contains a SETEOM macro instruction. If 
CONV= is coded with the ( opfield.switch ) option, LMD= cannot be coded with 
the ( opfieldySwitch ) option. Logical messages are discussed in Handling Logical 
Messages in the chapter Designing the Message Handler. 



i 



198 OS/MFT and OS/MVT TCAM Programmer's Guide 



INBLOCK 



The INBLOCK macro 

• identifies the beginning of an inblock subgroup, 

• is required if logical messages are to be handled by this MH, or if the 
MSGFORM macro is used on input, or if a character string specified on 
MSGEDIT may cross buffer boundaries, 

• if present, must precede the inheader subgroup. 

The INBLOCK macro, when used, must be the first macro following STARTMH. 
Otherwise, the INHDR delimiter macro must be the first instruction following 
STARTMH. 

The inblock subgroup may contain one, and only one, SETEOM functional macro. 
Other functional macros that may be included in this subgroup are Usted below. 
Their positions relative to SETEOM determine whether they operate on all data in 
an entire incoming transmission sequence, or whether they operate on one or more 
blocked or deblocked logical messages; any of the following functional macros 
that are issued before the SETEOM macro act on all the incoming data in a 
physical transmission sequence, and any issued after SETEOM act on one or more 
of the resulting logical messages. 

• CODE 

• COUNTER 

• LOG 

• LOCOPT 

• MSGEDIT 

. MSGFORM 

• MSGLIMIT 

• PATH 

. SETEOM 
. TERRSET 



symbol 



Name 


Operation 


Operand 


[symbol] 


INBLOCK 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



PATH=(opfield,switch) 



Function: Specifies conditional execution of this macro. 
Default: None. Specification optional. 

Format: (opfield.switch) . opfield must conform to the rules for assembler lan- 
guage symbols, and must be the name of a one-byte option field defined by an 
OPTION macro, switch may be either decimal or hexadecimal. If hexadecimal 
format is used, framing X' ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 

Notes: If this operand is not specified, the subgroup is executed unconditionally. 



Designing the Message Handler 199 



INHDR 



symbol 



PATH=(opfield,switch) 



The INHDR macro 

• identifies the beginning of an inheader subgroup; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro of any incoming group if the INBLOCK macro is 
not specified. 

INHDR identifies the beginning of an inheader subgroup, in which the functional 
macros are concerned only with incoming header segments. If the inblock sub- 
group is not required, an inheader subgroup must be the first subgroup in the 
incoming group. If MSGFORM on input is specified, or if MSGEDIT is used 
across buffer boundaries, or if incoming logical messages are being handled by this 
MH, an inblock subgroup must be the first subgroup in the incoming group. Text 
segments are passed to the first inbuffer subgroup. 

INHDR determines whether an incoming message segment is a header or text 
segment (the first segment of any message is always considered to bea header 
segment). If it is a text segment or a canceled message, the segment is passed to 
the next subgroup; if it is a header segment, the inheader subgroup is executed. 

If the PATH= operand of INHDR is coded, INHDR examines a one-byte path 
switch in a field of the option table. If any of the bits specified by INHDR are on 
in the path switch, this subgroup is executed. If none of the bits are on, control is 
directed to the next subgroup. If INHDR does not specify an operand, this 
subgroup is executed unconditionally. For a more complete description of the 
path switch and its function, see Variable Processing within a Message Handler 
in this chapter. 



Name 


Operation 


Operand 


[symbol] 


INHDR 


[PATH= (opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro. 

Default: None. Specification optional. 

Format: (opfield,switch). opfield must conform to the rules for assembler 

language symbols, and must be the name of a one-byte option field defined by an 

OPTION macro, switch may be either decimal or hexadecimal. If hexadecimal 

format is used, framing X' ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 

Notes: If this operand is not specified, the subgroup is executed unconditionally. 



{ 



200 OS/MFT and OS/MVT TCAM Programmer's Guide 



INBUF 



symbol 



PATH=(opfield,switch) 



The INBUF macro 

• identifies a subgroup that handles incoming message buffers; 

• tests a path switch to allow alternative courses of action; 

• is optional in the incoming group. 

INBUF identifies the beginning of an inbuffer subgroup, which contains instruc- 
tions concerned with both header and text portions of incoming messages. 

If the PATH= operand of INBUF is coded, INBUF examines a path switch in a 
field of the option table. If any of the bits specified by INBUF are on in the path 
switch, this subgroup is executed. If none of the bits specified by INBUF are on 
in the path switch, processing goes to the next subgroup. If INBUF does not 
specify an operand, this subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


INBUF 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



Designing the Message Handler 201 



INMSG 



The INMSG macro 

• identifies the beginning of an inmessage subgroup; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro in an inmessage subgroup; 

• is optional in the incoming group. 

INMSG identifies the beginning of an inmessage subgroup. The functional 
macros associated with this subgroup are executed after an entire message or 
block has entered the system. Inmessage subgroups are specified after other 
subgroups in the incoming group. No user-written code should be included in an 
inmessage subgroup, or between such subgroups. 

If the PATH= operand of INMSG is coded, INMSG examines a path switch in a 
field of the option table. If any of the bits specified by INMSG are on in the path 
switch, this subgroup is executed. If none of the bits specified by INMSG are on, 
processing branches to the next subgroup. If INMSG does not specify an oper- 
and, this subgroup is executed unconditionally. Only one inmessage subgroup per 
message can be executed. 



INMSG causes empty buffer units at the end of a buffer processed by this Mes- 
sage Handler to be deallocated before the contents of the buffer are queued for a 
destination. Deallocated units are returned to the available unit queue. When the 
inmessage subgroup is not included in a Message Handler, this deallocation 
function is performed by the INEND macro. 



Name 


Operation 


Operand 


[symbol] 


INMSG 


[PATH=(opfield,switch)] 



symbol 



PATH = (opf ie W,switch) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



i 



202 OS/MFT and OS/MVT TCAM Programmer's Guide 



INEND 



The INEND macro 

• identifies the end of the incoming group of an MH; 

• is required as the last macro of any incoming group. 

INEND identifies the end of the instruction sequence that processes incoming 
messages. One and only one INEND macro is required for each MH with an 
incoming group, and it must be the last macro in the incoming group. No operand 
is required. 



Name 


Operation 


Operand 


[symbol] 


INEND 


(no operands) 



ymbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands for this macro. 



Designing the Message Handler 203 



OUTHDR 



The OUTHDR macro 

• identifies the beginning of an outheader subgroup; 

• tests a path switch to allow alternative courses of action; 

• is optional in an outgoing group. 

OUTHDR identifies the beginning of an outheader subgroup, which is concerned 
only with the header portions of outgoing messages and, if included, may be either 
before or after an outbuffer subgroup in the outgoing group. 

An outgoing segment is tested to see whether it is a header or a text segment. The 
outheader subgroup is executed only on a header segment; it is bypassed if the 
segment contains text only. 

If the PATH= operand of OUTHDR is coded, OUTHDR examines a path switch 
in a field of the option table. If any of the bits specified by OUTHDR are on in 
the path switch, this subgroup is executed. If none of the bits are on, control 
passes to the next subgroup. If OUTHDR does not specify an operand, this 
subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


OUTHDR 


[PATH=(opfield,switch)] 



symboi 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



1 
% 



PATH = (opf ield,switch) 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



{ 



204 OS/MFT and OS/MVT TCAM Programmer's Guide 



OUTBUF 



ivmbol 



The OUTBUF macro 

• identifies a subgroup that handles outgoing message buffers; 

• tests a switch to allow alternative courses of action; 

• is optional in an outgoing group. 

OUTBUF identifies the beginning of an outbuffer subgroup that contains instruc- 
tions concerned with both header and text portions of outgoing messages. If 
included, an outbuffer subgroup may be located either before or after an out- 
header subgroup in the outgoing group. 

If the PATH= operand of OUTBUF is coded, OUTBUF examines a path switch 
in a field of the option table. If any of the bits specified by OUTBUF are on in 
the path switch, this subgroup is executed. If none of the bits specified by 
OUTBUF are on, control passes to the next subgroup. If OUTBUF does not 
specify an operand, this subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


OUTBUF 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



PATH=(opfield,switch) 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



Designing the Message Handler 205 



OUTMSG 



symbol 



PATH=(opfield,switch) 



The OUTMSG macro 

• identifies the beginning of an outmessage subgroup of an MH; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro in an outmessage subgroup; 

• is optional in an outgoing group. 

OUTMSG identifies the beginning of an outmessage subgroup, which is executed 
only after an entire block or message has been sent. Outmessage subgroups are 
specified after other subgroups in the outgoing group. 

If the PATH= operand of OUTMSG is coded, OUTMSG examines a path switch 
in a field of the option table. If any of the bits specified by OUTMSG are on in 
the path switch, this subgroup is executed. If none of the bits specified by 
OUTMSG are on, control passes to the next subgroup. If OUTMSG does not 
specify an operand, this subgroup is executed unconditionally. Only one 
OUTMSG subgroup per message can be executed. 

OUTMSG causes empty units at the end of buffers handled by this outgoing group 
to be deallocated and returned to the available unit queue. If an outmessage 
subgroup is not coded, this deallocation function is performed by OUTEND. 



Name 


Operation 


Operand 


[symbol] 


OUTMSG 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



( 



206 OS/MFT and OS/MVT TCAM Programmer's Guide 



OUTEND 



symbol 



The OUTEND macro 

• identifies the end of any outgoing group; 

• is required as the last macro in any outgoing group. 

OUTEND identifies the end of the instruction sequence that processes outgoing 
messages. One OUTEND macro is required for each outgoing group; it must be 
the last macro in the group. No operands are required. 



Name 


Operation 


Operand 


[symbol] 


OUTEND 


(no operands) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands for this macro. 



Designing the Message Handler 207 



i 



Functional Macro Instructions 

This section describes the functions provided by the MH macro instructions. The 
discussion of each macro begins with a capsule summary of its functions. The 
functions of the macro are then described in detail, with a discussion of related 
topics necessary to an understanding of these functions. 

The coding of the macro is then described, using a boxed illustration. The formats 
of the macro illustrations and the symbols used are shown in Appendix A . 
General rules for interpretation of the operand descriptions are also provided in 
Appendix A , to which the reader should refer. 



Designing the Message Handler 209 



CANCELMG 



The CANCELMG macro 

• cancels messages either unconditionally or when certain errors occur (or, if 
mid-batch recovery is specified on this macro, permits the user to continue 
entering data when TCAM detects an error); 

• is optional in an inmessage subgroup (and is permitted in no other subgroup); 

• if specified, must be the first functional macro executed in the subgroup. 

For messages other than multiblock messages, CANCELMG causes immediate 
cancellation of an entire message if any errors specified by the error mask operand 
are also set in the message error record (see Appendix B for a description of the 
message error record). A canceled message is not sent to any of its destinations. 

The ERRORMSG or MSGGEN macro may be used to notify the terminal opera- 
tor of the error, or the REDIRECT macro may be used to send the message that is 
in error to a selected destination. 

For a multiblock message, CANCELMG stops processing the message from the 
point that an error is detected. Once the terminal operator resumes input (starting 
with the block immediately after the last entire block successfully entered), the 
remainder of the multiblock message is processed by this MH. 

Note: CANCELMG should not be executed for a message if an INITIATE 
macro has been executed for that message. 



If the CANCELMG macro is executed in the inmessage subgroup for a lock mode 
message, the lock is not broken and the terminal will be repoUed. 



Name 


Operation 


Operands 


[symbol] 


CANCELMG 


[mask][,CONNECT= ( AND) ] [,LEVEL=(BLK ) ] 
I OR 1 iMSGj 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X' ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field five bytes in length. 
Notes: If the LEVEL= operand is not specified, and this operand either specifies 
an all-zero mask or is omitted, CANCELMG executes unconditionally. 



i 



210 OS/MFT and OS/MVT TCAM Programmer's Guide 



CONNECT= (AND 
/OR 



LEVEL= JBLK / 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



Function: Specifies mid-batch recovery for errors detected in multiblock messages. 
Default: LEVEL=MSG. If mid-batch recovery is desired for incoming multi- 
block messages, this operand is required. 
Format: BLK or MSG. 

Notes: When this operand is specified and TCAM detects a permanent error after 
the first block of an incoming multiblock message, TCAM queues all error-free 
data up to the error (but not including the error) before it resumes receiving 
operations for the line. The station operator can then correctly reenter that 
portion of the message beginning with the data following the last successfully 
transmitted block. See mid-batch recovery elsewhere in this pubhcation. 

If multiple CANCELMG macros are issued in the same inmessage subgroup, only 
the first may specify LEVEL = BLK, and there may be no other macros issued 
between CANCELMG macros. 

If an error mask is specified when LEVEL=BLK is specified, the CONNECT= 
operand must specify OR. 

Example 1 : 

CANCELMG X ' 00000801 00 ' , CONNECT=AND 

specifies that the message is to be canceled only if bits 20 and 3 1 of the message 
error record are both on. 

Example 2: 

CANCELMG 524544 , CONNECT=OR 

specifies that the message is to be canceled if either bit 20 or bit 3 1 of the message 
error record is on. 



Designing the Message Handler 211 



CHECKPT 



symbol 



The CHECKPT macro 

• causes an incident checkpoint record to be taken of the option fields for the 
originating or destination station or apphcation program; 

• may be coded in any subgroup of the Message Handler except the inblock 
subgroup. 

When coded in an inheader, inbuffer, or inmessage subgroup, the CHECKPT 
macro causes an incident checkpoint record to be made of the option fields 
assigned to the originating station or application program. This checkpoint record 
is taken after the entire incoming group has executed and the message has been 
enqueued, so that the option fields reflect the fact that a message has been 
processed by the incoming group. 

When coded in an outheader, outbuffer, or outmessage subgroup, CHECKPT 
causes an incident checkpoint record to be taken of the option fields assigned to 
the destination station or application program. This checkpoint record is taken 
after the entire outgoing group has been executed and the message has been sent. 
The option fields reflect the fact that a message has been sent by the outgoing 
group. 

If a message segment goes through any subgroup in which a CHECKPT macro is 
executed, an incident checkpoint record is made after that message has been 
completely handled by the appropriate MH group. Only one record per message 
is made, even if more than one CHECKPT macro is coded in the group. If no 
CHECKPT record is coded in a group, no incident checkpoint record is made 
when the message leaves the group. 

For more information on TCAM's checkpoint facility, see the chapter Using 
TCAM Service Facilities. 

CHECKPT has the following format: 



Name 


Operation 


Operands 


[symbol] 


CHECKPT 


(no operands) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

The CHECKPT macro has no operands. 



i 



212 OS/MFT and OS/MVT TCAM Programmer's Guide 



CODE 



The CODE macro 

• translates the data in the buffer being handled; 

• tests for operator commands; 

• is optional in the inblock, inheader, inbuffer, outheader, and outbuffer sub- 
groups (and not permitted in any other subgroups); 

• may be issued at any point in the subgroup. 

CODE causes the message segment being handled to be translated. If specified in 
an inblock, inheader, or inbuffer subgroup, translation is from line code to 
EBCDIC; if specified in an outheader or outbuffer subgroup, translation is from 
EBCDIC to the line code. Translation should not be performed in the Message 
Handler for an application program because both the Message Handler and the 
application program work on EBCDIC data. CODE may be issued with no 
translation if operator control is desired in the application program. The line code 
to be used is specified by the TRANS= operand of the DCB macro or by an 
operand of the CODE macro (which overrides the table specified in the DCB 
macro). 

If CODE is included in a subgroup, and any segments of a message are processed 
by that subgroup, the entire message is translated (special considerations for 
logical messages are discussed following the example below). Macros issued 
before CODE in the incoming group act on message characters that are in line 
code, while macros issued following CODE act on message characters that are in 
EBCDIC. The converse is true for the outgoing group. If CODE is not included 
in the incoming group, incoming messages are not translated; if CODE is not 
included in the outgoing group, outgoing messages are not translated. 

Once a message has been translated by a CODE macro executed in a subgroup of 
an incoming or outgoing group, care should be taken that no segment of it is 
routed through another subgroup when the second subgroup also contains a 
CODE macro. The second CODE macro would 'translate'' the message into 
gibberish. 

The CODE macro permits flexibility of handling of buffers with respect to 
translation by overriding the translation table specified for the line group. 

CODE tests for operator commands and transfers control accordingly. If operator 
commands may be entered by any station on a line, then a CODE macro should 
be issued in the inheader subgroup of the MH handling incoming messages on that 
line. If the LC= operand of the STARTMH macro is coded LC=OUT (that is, if 
line-control characters are to be automatically stripped from incoming messages), 
then CODE should be the first functional macro issued in either the inblock or the 
inheader subgroup for a line on which operator commands may be entered. If 
STARTMH is coded LC = IN (if line-control characters are not to be removed 
from incoming messages by TCAM), then a SETSCAN macro should be issued 
immediately before CODE. The SETSCAN macro should move the scan pointer 
to the last of the initial line-control characters. 

The user may wish to enter one or more characters in front of the character string 
that identifies his operator command. This is permissible as long as the user sets 
his scan pointer to the nonblank character immediately preceding the operator 
control character string before issuing CODE. 



Designing the Message Handler 213 



The CODE macro must be issued in either the inblock or the inheader subgroup 
handling messages from a station, if operator commands may be entered by that 
station. However, the user may not wish to translate other messages entered at the 
station. One way to avoid having to translate every message follows (assume that 
line code is removed from incoming messages). 

Code a special inheader subgroup as the first subgroup of the incoming group; this 
special subgroup may consist of a MSGTYPE macro followed by a CODE macro. 
The MSGTYPE macro examines the first field in each incoming message in Hne 
code and executes only if this field consists of some specific character — for 
instance A. Enter A before the identification sequence of each operator com- 
mand. If the first character of a message is A, the CODE macro will execute, and 
the message will be translated — otherwise, control will be passed to the next 
delimiter, which may be another inheader subgroup designed to handle messages 
other than operator commands in line code. 

Example: 

The following code might be used to check for operator commands entered at a 
1050 station, and to cause each incoming message to be translated only if it is ail 
operator command. It is assumed that line code is removed from incoming 
messages and that the operator at the station enters an A immediately in front of 
the identification sequence for an operator command. 

OCMH STARTMH LC=OUT , STOP=YES 

OCCFIK INHDR 

MSGTYPE X'E2' 

CODE 
NONOC INHDR '4 

INBUF 

INMSG 

INEND 

An incoming message enters the first inheader subgroup. If A (which is X'E2' in 
1050 line code) is the first character in the message, CODE is executed. If this is 
an operator command, the CODE macro causes it to be handled as such, and it 
never reaches the second inheader subgroup. A message that does not begin with 
A is not translated and is passed to the second inheader subgroup, which contains 
macros that handle ordinary (not operator control) messages. 

The CODE macro instruction provides the same functions for logical messages 
(translation and checking for operator commands) as those described above. 
However, the following special considerations apply to the CODE macro when it 
is used in the inblock subgroup handling incoming messages to be deblocked into 
multiple logical messages. Logical messages formed by blocking incoming physi- 
cal transmissions require no special considerations. Logical messages are dis- 
cussed in Handling Logical Messages in this chapter. 



(i 



i 



214 OS/MFT and OS/MVT TCAM Programmer's Guide 



The format of an incoming physical transmission that is to be deblocked is 




E 
O 
M 



^ 



m^. 



E 
O 

M 



^^^^Mfei^^ 



M 



M^^^/I^^^&l 



E 
O 

T 



symbol 



( tablename 

^NONE 
I (register) 



where P is all the data in the entire physical transmission and L1-L3 are the logical 
messages that will result from deblocking P. 

When the CODE macro is issued in the inblock subgroup before the SETEOM 
functional macro, all the incoming data (P) is translated. If logical messages LI, 
L2, and L3 are to be checked to determine if they are operator commands, the 
inheader subgroup of this incoming group must contain another CODE macro 
specifying NONE. 

When issued after the SETEOM macro, CODE functions in the same manner as 
described in the section preceding the example above, except that the CODE 
macro cannot be used to check for operator commands. 

CODE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CODE 


[^tablename^ ] 

<[none . > 

((register) ) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary .) 



Function: Specifies the type of translation to be done. 

Default: None. Specification optional. 

Format: tablename, (register) or NONE, tablename must either be one of the 

names permitted for the TRANS = operand of the DCB macro or the name of a 

user-defined table that conforms to the rules for assembler language symbols. 

(register) must specify a decimal integer between 2 and 1 1 . 

Notes: If this operand is omitted, the table used for translation is that specified by 

the TRANS= operand of the DCB macro. 

If NONE is specified, the message is not translated. None can be used to check 
for operator commands when the station transmits in EBCDIC. 



Designing the Message Handler 215 



If (register) is specified, the register must previously have been loaded with the 
address of the table to be used* A user-defined translation table must consist of a 
fuUword on a fuUword boundary, followed by a 256-byte table for translating (| 

from Une code into EBCDIC^ followed by a 256-byte table for translating from 
EBCDIC into hne code. The first word must contain the address of the first byte 
of the second table. The high-order byte of the first word must be zero. 



i 



216 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



LIST=name 



lVIAXDEEP=mteger 



COMMBUF 



The COMMBUF macro 

• is optional in the inheader and inbuffer subgroups of an MCP that supports 
3670 terminals equipped to receive broadcast messages; 

• routes broadcast messages to the destinations specified in the indicated TLIST 
macro. 

COMMBUF has the following format: 



Name 


Operation 


Operand 


[symbol] 


COMMBUF 


LIST=name,MAXDEEP=integer 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of a TLIST macro that should contain the names of 
the broadcast terminals (TERM=367C on the TERMINAL macro). 
Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the maximum number of broadcast operations that may be 

scheduled for a line at any one time. 

Default: None. This operand must be specified. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 

Notes: The COMMBUF macro moves the data in the current buffer into one of 

the data areas specified at INTRO time. Therefore, any MH macros following 

COMMBUF will have no effect on the data sent by the common buffer facility. If 

the length of the data to be moved is greater than the size of a data area, the 

macro will not execute, and a return code will be given in register 15 (see return 

codes). 



Designing the Message Handler 217 



The common buffer facility allows data entering the input MH to be sent without 
being queued. There is no outgoing message handhng capability for this data. 
The data in the current buffer will be moved to the next available data area, and a 
broadcast operation will be scheduled for each of the lines whose broadcast 
terminals are named in the TLIST macro if the MAXDEEP= value has not been 
exceeded and if the line is active. If the MAXDEEP= value has been exceeded, 
the data in the current buffer is not moved and is not broadcast. 

Framing line control characters (STX, ETX) must be supplied by the user and 
there should not be any embedded ETBs. 

COMMBUF will return the following codes in register 15: 

00 Good return 

04 Data area too small; macro did not execute (the data area size specified 

in the COMMBUF = operand of the INTRO macro was too small). 

08 MAXDEEP value exceeded (register 1 will contain the number of 

times MAXDEEP was exceeded). 

OC LIST= operand specified a name that was not a TLIST entry. 



< 



2 1 8 OS/MFT and OS/M VT TC AM Programmer's Guide 



I 



COUNTER 



The COUNTER macro 

• maintains a count of complete messages or of message segments received from 
or sent to a station; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups. 

COUNTER enables the user to maintain four types of count. The position of the 
COUNTER macro within an MH determines which type of count is maintained. 
COUNTER may appear: 

• in the inblock subgroup to count incoming physical message segments arriving 
at this MH, or incoming logical message segments for each originating station; 

• in the inheader subgroup to count incoming messages for each originating 
station; 

• in the inbuffer subgroup to count incoming message segments for each originat- 
ing station; 

• in the outheader subgroup to count outgoing messages for each destination 
station; 

• in the outbuffer subgroup to count outgoing message segments for each destina- 
tion station. 

Any one or more of the counts may be maintained by including COUNTER in the 
appropriate subgroups; within each subgroup, it may appear at any point. 

For each COUNTER macro, the user must define, by an OPTION macro, a 
halfword option field for the appropriate station or component. This provides 
space for maintaining the counters. 

The use of COUNTER is optional. If it is used in either an inheader or or an 
inbuffer subgroup for switched stations that do not have unique ID sequences, and 
if a calling station that enters a message is not identified by an ORIGIN macro 
before COUNTER is executed, the option field associated with the related Une 
entry in the terminal table will be referred to. 

Note: The count may not be exact since recalled messages (from 
ERRORMSG, for instance) and messages from buffered stations will be 
counted twice. 

If the MH includes the SETEOM macro, the number of times the COUNTER 
macro executes depends on the PROCESS = operand of SETEOM and on the 
position of the COUNTER macro relative to the SETEOM macro. 

If the SETEOM macro specifies PROCESS=NO, the COUNTER macro always 
adds one to the counter for each resulting blocked logical message. 

If the SETEOM macro specifies PROCESS=YES, and if the COUNTER macro 
appears before SETEOM, one is added to the counter to reflect each buffer in the 
entire incoming transmission sequence; however, if COUNTER appears after 
SETEOM (that is, after the data is deblocked), each buffer of each resulting 
logical message causes a counter to be updated by one. In the latter situation, if a 
counter is associated with each station that is eligible to enter messages to this 
MH, a count is maintained for incoming logical messages on a station basis. 

Logical messages are discussed in Handling Logical Messages in this chapter. 



Designing the Message Handler 219 



symbol 



opfield 



Name 


Operation 


Operands 


[symbol] 


COUNTER 


opfield 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the half word option field in which the count is to 

be maintained for the station or component. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols and must be 

the name of a halfword option field defined by an OPTION macro. 

Notes: The field contains a binary count up to a maximum of 65535. When the 

maximum count has been reached, the count is reset to zero for the next message 

or segment counted. 

The user may gain access to the field at any time to determine or reset the count 
(by operator commands or by user code including the LOCOPT macro). The 
count is initially set using the OPDATA= operand of the TERMINAL or 
TPROCESS macro. 



If the option field is not found. COUNTER does not execute and control passes to 
the next MH instruction. A return code of XTF' in the low-order byte of register 
15 indicates that COUNTER did not execute. 



( 



220 OS/MFT and OS/MVT TCAM Programmer's Guide 



CUTOFF 



symbol 



integer 



The CUTOFF macro 

• specifies the maximum allowable length of incoming messages; 

• checks for incoming buffers filled with identical characters; 

• is optional in the inbuffer subgroup (and not permitted in any other subgroup); 

• is usually issued before a related ERRORMSG macro. 

CUTOFF specifies the maximum number of characters allowed in an incoming 
message. If the maximum number is reached, reception of data is terminated as 
soon as those buffers already assigned to the Une have been filled, an error flag is 
set in bit 7 of the message error record for the message (see Appendix B ). 
CUTOFF also turns on bit 7 of the message error record if the input buffer is 
filled with identical characters (usually an indication of station malfunction). 

An ERRORMSG macro may be used in the same incoming message handler as the 
CUTOFF macro to test bit 7 of the message error record and to notify the 
terminal operator that reception of the message has been terminated. The opera- 
tor can determine if the allowed number of characters was exceeded; otherwise a 
station malfunction is indicated. After the CUTOFF macro has executed, 
processing continues through the inbuffer subgroup. 



Name 


Operation 


Operands 


[symbol} 


CUTOFF 


integer 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Function: Specifies the maximum number of characters allowed for each message. 

Default: None. This operand must be specified. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 

XLn* ' characters must be specified. 

Maximum: 65535 or a hexadecimal field of two bytes. 

Example: 

CUTOFF 400 

specifies that reception of the message is to be terminated after 400 characters 
have been entered. 

CUTOFF does not provide a precise limit to the number of characters in an 
incoming message (because TCAM continues to read until the buffers currently 
assigned have been filled). The inmessage subgroup is not executed until the line 
operation has terminated. When the CUTOFF condition is encountered, a Write 
Break is issued for the Telegraph Adapter I. For IBM Adapter III Model 1, a 
2848 Read Skip with 2848 Break is issued. For all other devices, a Read Skip is 
issued when the CUTOFF condition is encountered. 

Note: Once the CUTOFF condition is encountered, the CUTOFF macro 
must be executed for each subsequent buffer of the message. 



Designing the Message Handler 22 1 



i 



symbol 



DATETIME 



The DATETIME macro 

• inserts the date, the time, or both in an incoming or outgoing message header; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroup); 

The DATETIME macro causes insertion of the date, the time, or both the date 
and the time into the header of an incoming or outgoing message. (If both are 
specified, the date is inserted first.) Seven characters are inserted for the date, if 
specified: a blank, the last two digits of the year, a period, and the three-digit day 
number. Nine characters are inserted for the time, if specified: a blank, two digits 
for the hour, a period, two digits for the minute, a period, and two digits for the 
second. If no operand is coded, both the date and the time are provided (the 
operands specify which is to be omitted). 

Space in the header for these insertions, seven characters for the date and nine 
characters for the time, must be reserved by the RESERVE= operand of the DCB 
macro for the communication line or by the RESERVE = operand of the PCB 
macro for the application program, if the insertions are desired. After 
DATETIME has executed, the scan pointer is positioned at the last inserted 
character. 

When the DATETIME macro is coded in an outgoing subgroup, the macro may 
operate upon the first message segment only. This is because TCAM does not 
maintain reserve bytes for any segment of an outgoing message except the first 
(see the description of the RESERVE= operand of the DCB macro). 

To avoid having to specify a large first buffer, the user who wishes to insert both 
the date- and time-received and the date- and time-sent in the same message 
header may design his header so that it occupies two buffers. He could then insert 
the incoming date and time in that portion of the header contained in the second 
buffer, and the outgoing date and time in that portion of the header contained in 
the first buffer. 

The characters inserted by DATETIME are in EBCDIC code. Therefore, the 
DATETIME macro should not be issued before a CODE macro in an inheader 
subgroup, or after a CODE macro in an outheader subgroup. 



Name 


Operation 


Operands 


[symbol] 


DATETIME 


[DATE= J NO V|[,TIME=f NO ^ 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary .) 



) 



Designing the Message Handler 223 



DATE=(NO ) 
)YES\ 



Wes{ 



Function: Specifies whether the date is to be inserted in a message header. 

Default: DATE=YES 

Format: YES or NO. 

Notes: YES specifies that the date is to be inserted in the message header. NO 

specifies that the date is to be omitted from the header. 



Function: Specifies whether the time is to be inserted in a message header. 

Default: TIME=YES 

Format: YES or NO. 

Notes: YES specifies that the time is to be inserted in the message header. NO 

specifies that the time is to be omitted from the header. 

If no operand is coded, both the date and the time are inserted in the message 
header. 

The time inserted is the time at which this DATETIME macro is executed. 
TCAM determines this by examining the system timer. 

If insufficient buffer space is available (too few reserve characters), the 
DATETIME macro does not execute and a X'04' return code is set in register 15. 

Example: 

The message 

NYC 0039 * ( message text ) EOT '4 

is entered at the NYC terminal (NYC is the origin, 0039 the input sequence 
number). If the header buffer is being processed at 9:45:50 p.m. on February 6, 
1970 and if the SEQUENCE macro is followed by DATETIME DATE=NO, the 
time is inserted in the header, which becomes: 

NYC 0039 2 1 . 45 . 50 * ( message text ) EOT 

If the SEQUENCE macro is followed by DATETIME, the header becomes: 

NYC 0039 70.037 21 .45.50 * (message text ) EOT 



< 



224 OS/MFT and OS/MVT TCAM Programmer's Guide 



ERRORMSG 



The ERRORMSG macro 



• sends an error message when an error occurs; 

• is optional in an inmessage or outmessage subgroup of an MH (and not permit- 
ted in any other subgroup); 

• may be used more than once in a subgroup. 

ERRORMSG sends an error message specified by the user to a designated station 
when errors indicated by the error mask have occurred. The bits specified by the 
error mask operand are compared with the setting of the bits in the message error 
record for this message; if specified bits in the message error record are on, the 
error message is sent. The message may be sent unconditionally by specifying an 
all-zero mask, or by omitting the mask. 

The message sent to the station includes the text written by the user preceded by 
the header of the message in error, which is recalled from the message queue. The 
error message, once formatted, is placed on the destination queue for the station 
selected to receive the message, and is handled by the outgoing group of the MH 
for that queue. Therefore, unless a MSGTYPE or PATH macro is used to distin- 
guish between different message types, the format of the header of the message in 
error must be compatible with the macros executed in the outgoing group handling 
messages routed to the station selected to receive the error message. If the 
MSGTYPE macro is used for this purpose, the formats of the respective headers 
may differ after the message-type character. 

y The outgoing group that handles the error message for the destination station may 

^ have an outmessage subgroup containing ERRORMSG and REDIRECT macros. 

TCAM causes these macros to NOP; that is, TCAM does not generate subsequent 
error messages based on an error condition related to the original error message 
(thus preventing a "snowball" effect of error messages); and TCAM does not 
permit the error message to be redirected to an alternate destination. 

If the MSGFORM macro is not coded in the outheader subgroup of the MH 
handling messages for the destination station, the user must ensure that satisfacto- 
ry line-control characters (such as EOT) are included in his error message. 

The user may prefer to use the MSGGEN function if the message header is not 
required as a part of the error message. The user is notified of the error sooner if 
he uses MSGGEN than ERRORMSG, but ERRORMSG returns the header of the 
message in error, while MSGGEN does not. If it is necessary to send an error 
message for input errors when no data has been transferred, the MSGGEN macro 
must be used because the ERRORMSG macro requires a header. 

If cancellation of an erroneous message is required, the CANCELMG macro must 
have been issued before the ERRORMSG macro. ERRORMSG may appear in 
inmessage and outmessage subgroups and can appear more than once in either 
subgroup. 

Since the header of the message in error is recalled from the destination queue, it 
is not possible to use ERRORMSG coded DEST=DESTIN when the destination 
of the message in error is not known to TCAM. If a message having an invaUd 
1 destination field is entered, and the destination is not corrected by the user-exit of 

^ the FORWARD macro, and if no dead-letter queue is specified by the INTRO 



Designing the Message Handler 225 



symbol 



macro, then ERRORMSG cannot be used in conjunction with that message, 
because the message header is not on a destination queue (consequently, TCAM 
cannot get a copy of the header by recalling it from a destination queue). 



Name 


Operation 


Operands 


[symbol] 


ERRORMSG 


[mask][,CONNECT= lANDM 
<OR > 

[,DEST= /'destination name^] 
)opfield ( 
) ORIGIN r 

(destin ) 

,D ATA = J message ) 
I fieldname) 
[, EXIT = name of routine] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in AppendijS ) 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X * ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting this operand or specifying an all-zero mask causes uncondition- 
al execution. 






CONNECT=JAND/ 
JOR S 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



DEST= ( destination name "; 
) opfield 
) ORIGIN 
V DESTIN 



Function: Specifies the destination for the error message. 

Default: In an inmessage subgroup, DEST= ORIGIN. 

In an outmessage subgroup, DEST=DESTIN. 

Format: destination name, opfield, ORIGIN or DESTIN. destination name is the 



i 



226 OS/MFT and OS/MVT TCAM Programmer's Guide 



DATA= { message ) 
( fieldname ) 



name of a single or a process entry in the terminal table and must be enclosed in 
framing C ' or CLn* ' characters. 

opfield is the name of an option field defined by an OPTION macro, conforming 
to the rules for assembler language symbols, which contains the name of a single 
or process entry in the terminal table. It must not be specified with framing 
characters, opfield is a field from two to nine bytes, with the first byte containing 
the decimal length of the rest of the field. 

ORIGIN specifies that the error message is to be sent to the station from which 
the message originated. This operand may be specified in either an inmessage or 
outmessage subgroup. If the originating station is not known (because it called in 
on a switched line and did not identify itself) the message is sent to the dead-letter 
queue if one is specified, otherwise it is lost. 

DESTIN specifies that the error message is to be sent to the destination station 
specified in the header of the message in error. This operand may be specified in 
either an inmessage or outmessage subgroup. 

Notes: If an invaUd destination is specified, or if DESTIN is specified in an 
inmessage subgroup for which no FORWARD macro has been issued previously, 
the message is sent to the dead-letter queue if one has been specified by the 
DLQ= operand of the INTRO macro. If no dead-letter queue is specified, the 
message is overlaid and lost. 

A distribution Ust or a PUT process entry must not be specified as the destination 
of an error message. 



Function: Specifies the error message. 
Default: None. This operand must be specified. 

Format: message or fieldname, message is the actual error message to be sent 
and must be specified within framing C ' or CLn' ' characters, fieldname is the 
name of a location containing in its first byte a binary count of the number of 
characters in the message, followed by the message itself. The error message is a 
maximum length of 255 characters. This is exclusive of the binary count in the 
fieldname format. 

Notes: If an error message is longer than a single buffer unit, one additional 
buffer unit is obtained and as much of the remainder of the message as will fit is 
placed in it. If the entire message will not fit into these two units, the remainder is 
truncated on the right. 



EXIT = name of routine 



Function: Specifies the name of a user- written routine that alters error message 
processing. This exit may be used to alter the text of the error message before 
incorporating the text into a header buffer. 
Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 
Notes: If the user provides an exit routine for ERRORMSG, TCAM automati- 
cally saves and restores registers for this routine. The user need not save registers 
and may change the contents of registers 2 through 12; however, the contents of 
register 13 and 14 should not be altered by the user routine. When the routine 
receives control, register 1 contains the address of the header buffer and register 5 



Designing the Message Handler 227 



contains the address of the error-message text. Register 14 contains the return 
address for the caUing routine. Register 15 contains the address of the entry point 
for the user routine. TCAM expects no return code from the user routine. The 
routine should return control to TCAM by a BR 14 instruction. 

When ERRORMSG is executed, only the first buffer of the message in error is 
retrieved from the destination queue (if the header occupies more than one buffer, 
that portion of the header extending beyond the first buffer is not retrieved). The 
actual error message is placed in that portion of the first header buffer that 
contains message text; the error message overlays the text. If the first buffer is 
entirely filled with header information, or does not contain enough space after the 
header to hold the entire error message, TCAM automatically assigns one extra 
unit to the buffer to hold as much as possible of the remainder of the message. If 
the entire message will not fit, the remainder is truncated on the right. 

The message is inserted in the header beginning at the current location of the scan 
pointer. If an ERRORMSG macro is issued in the inmessage subgroup, but there 
is additional header information that could be recognized by the outheader 
subgroup, the message will overlay this data, which will be lost for outgoing 
processing. If data has been inserted or removed during inbuffer or outbuffer 
processing, the data in the buffer will be moved either to the right or the left while 
the scan pointer remains fixed. Thus, when the error message is inserted at the 
scan pointer, data that is logically part of the header may be lost, or data beyond 
the header may be included as part of the header information returned with the 
message. 



i 



228 OS/MFT and OS/MVT TCAM Programmer's Guide 



FORWARD 



The FORWARD macro 

• queues messages for one or more specified destinations; 

• sets a bit in the message error record when a specified number of queued 
messages is exceeded for a destination using main-storage-only queuing; 

• is required in each inheader subgroup of the MH for every station and applica- 
tion program that can enter messages directed to a specific destination. 

FORWARD allows scanning of the destination code field in the header of each 
incoming message and compares the field with the names of the terminal table 
entries. If the destination code is valid (a matching entry is found in the terminal 
table), FORWARD queues the message for the specified destination or destina- 
tions. If an invalid destination code (that is, one not appearing in the terminal 
table) is detected, control passes to the user routine specified by the EXIT= 
operand of FORWARD. If no user exit is specified, the message is queued for the 
station or application program specified by the DLQ= operand of the INTRO 
macro. If no station or application program is specified by DLQ=, and no user 
exit is provided, messages with invalid destination codes are overlaid and lost. 

Messages may be routed to one or more destinations: 

1 . To the single destination specified in the message header or named by an 
operand of the FORWARD macro. 

2. To the distribution Ust specified in the message header or named by an operand 
of the FORWARD macro. 

3. To the cascade list specified in the message header or named by an operand of 
the FORWARD macro. 

4. To the multiple destinations specified in the message header. The destination 
codes may be of equal length or of varying lengths. In the case of multiple 
destinations, an operand specifies the end-of-address character or characters 
included after the last destination code in the header of each incoming message. 

5. To the group entry in the terminal table specified in the message header or in 
an operand of the FORWARD macro. 

When multiple destinations are specified, only the first is checked for vaUdity at 
execution of the FORWARD macro. The secondary destinations are checked for 
validity only after the entire message has been received. The first invalid destina- 
tion will be routed to the station specified by the DLQ= operand of the INTRO 
macro otherwise it will be lost; any other invalid destinations will be ignored. 

If multiple destinations are specified in the message header, or if a distribution Ust 
is specified, once the incoming group has finished processing the message, copies 
are made and routed to the destination queue for each destination specified in the 
header or distribution list. 

A FORWARD macro must be included in each inheader subgroup handling 
messages destined for stations or application programs; otherwise the incoming 
group of the MH does not know where to route the message. 

If DEST= (number) or DEST=** is specified, the CODE macro must be executed 
before FORWARD, unless the line code is EBCDIC. 



Designing the Message Handler 229 



If DEST=ORIGIN is specified, the ORIGIN macro must be executed before the 
FORWARD macro for messages from switched terminals that do not have a hne 
entry. 

Note: Care must be taken in entering a character string in a destination 
field to ensure that it matches a terminal table entry, A character string 
entered in lower-case characters from an IBM 2770 station, for example, 
will not match a terminal table entry name that is in uppercase characters. 

FORWARD has the following format: 



Name 


Operation 


Operands 


[symbol] 


FORWARD 


[DEST=|destname 1 ] 
\opfield / 
)( number) ( 

JpUT ( 
1 ORIGIN \ 
\ REG(number) J 

[ ,EO A = characters] 

[,EXIT=name] 

[,THRESH=nn] 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 






DEST= I destname 
opfield 
(number) 

PUT 

** I 

ORIGIN 
REG(number) 



Function: Specifies the destination for the message. 
Default: DEST=** 

Format: destname, opfield, (number), PUT**, ORIGIN, or REG(number). 
destname is the name of a single, group, distribution list, cascade list, or process 
entry in the terminal table and must be specified with framing C ' , CLn' ', X' \ or 
XLn* ' characters, opfield is the name of a field defined by an OPTION macro 
containing the name of an entry in the terminal table. Framing characters must 
not be used, (number) is the number of characters in each of a list of one or more 
destinations. PUT is specified when the destinations of messages entered by an 
appUcation program are placed by the user in an application program work area. 
** specifies that there are one or more destination names of variable length in the 
message header. ORIGIN indicates that the message is to be returned to the 
originating station. REG(number) specifies the register containing the address of 
a work area that contains the name of the destination. 
Maximum: number can be a decimal field with a maximum value of 8. 
Notes: opfield refers to an option field that is 1 to 8 bytes. If the destination 
name is shorter than the length of the option field, the name must be padded to 
the right with blanks to fill the field. 



230 OS/MFT and OS/MVT TCAM Programmer's Guide 



EOA= characters 



EXIT=naine 



If (number) is specified, the destination names in the message header must all be 
the same length. Delimiting and embedded blanks are ignored. If this operand is 
specified and there is more than one destination, the EOA= operand must also be 
specified. 

If ** is specified, delimiting blanks must be used between destination names in the 
header, but there may not be any embedded blanks. If this operand is specified 
and there is more than one destination in the message, the EOA= operand must 
also be specified. 

DEST=PUT should be specified in the inheader subgroups of the MH assigned to 
an application program when the MH is to handle messages coming from an 
application program that has OPTCD=W coded in its output DCB macro, if the 
user wishes the message to go to the destination specified in the work area. For 
more information on specifying the destination of a message in the application 
program, see the discussion of the OPTCD= operand of the output DCB macro. 
Use of this operand is restricted to the case just described. 

If an invalid destination is specified, control passes to the user routine specified by 
the EXIT= operand. If no user exit is specified, the message is queued for the 
station specified by the DLQ= operand of the INTRO macro. If no station is 
specified by DLQ= and no user exit is provided, messages with invahd destination 
codes are overlaid and lost. 

If REG (number) is specified, register 2 through 12 may be used. The register must 
contain the addtess of a field that has the following format: 

byte = length of the destination name. 

byte 1 - n = destination name with the same characteristics and format as 

destname when BEST = destname. 



Function: Specifies the character or character string used after the last station 
name of a mutiple destination to delimit the destination field of the header. 
Default: None. With DEST= coded destname , opfield , or PUT, specification 
optional. With DEST= coded (number) or ** and multiple destinations in the 
message, this operand is required. 

Format: One to eight nonblank characters specified in character or hexadecimal 
format. If character format is specified, the field may be unframed or framed with 
C* ' or CLn' ' characters. If hexadecimal format is specified, the field must be 
framed with X' ' or XLn' ' characters, n must be the actual length of the charac- 
ters. 

Notes: If this operand is specified and DEST= is coded destname , opfield or 
PUT, the operand is ignored. 



Function: Specifies the name of a user-written exit routine that is given control 

when an invahd destination is detected. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The routine may correct the destination, provide another destination, or 

indicate that the message is not to be processed for a destination. If an invalid 

destination is provided by the user exit routine, the message is forwarded to the 

dead-letter queue if one is specified by the DLQ= operand of the INTRO macro. 

Otherwise it is overlaid and lost. 



Designing the Message Handler 231 



THRESH=nii 



If the user provides an exit routine for FORWARD, TCAM automatically saves 
and restores registers for this routine. The user routine need not save registers 
and may change the contents of registers 2 through 12. However, the contents of 
register 13 and 14 should not be altered. When the user routine receives control, 
register 1 contains the address of the header buffer. Register 14 contains the 
return address for the calling routine. Register 15 contains the address of the 
entry point for the user routine. 

TCAM expects the user routine to place one of two items in register 15 before 
returning control: 

• A return code of all zeros in register 1 5 means that the user routine was unable 
toprovide a satisfactory destination for this message. In this case, the message 
is forwarded to the dead-letter queue or is not processed for any destination if 
no dead-letter queue is provided. 

• Register 15 may contain the main-storage address of a field set up by the user 
and consisting of a length byte followed by the name of a valid single, group, 
distribution Ust, cascade list, or process entry in the terminal table. The length 
byte must contain in binary form the number of bytes in the rest of the field. 
TCAM assumes that the specified name is the destination of the message. The 
field must be padded to the right with blanks to the length of the longest entry. 

The user routine should return control to TCAM by a BR 14 instruction. 
This operand is ignored when DEST=PUT is specified. 



Function: Sets a bit in the message error record indicating that a user-specified 
number of messages have been queued for a destination that uses main-storage- 
only queuing. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X* ' or 
XL2* ' characters must be specified. 
Maximum: 65535 

Notes: nn is a user-specified number that indicates the maximum number of 
messages expected to be queued at any one time under normal traffic conditions 
for a destination that uses main-storage -only queuing. This operand causes 
TCAM to queue a message and set bit six in the message error record when the 
number of messages queued exceeds nn . 

If the destination is an application program, this operand permits the user to delay 
activation of an apphcation program until a certain number of messages are 
queued for that destination. This operand can be used also as an aid in controlling 
the efficient use of system resources when one or more destinations use main- 
storage-only queuing. For instance, to prevent main storage being tied up with 
unsent messages, the user might provide a warning of an excessive number of 
messages queued for a particular destination; he could then issue a conditional 
macro in his inmessage subgroup such as CANCELMG, REDIRECT, 
ERRORMSG, and MSGGEN. If there are multiple destinations, the REDIRECT, 
ERRORMSG, and MSGGEN macros are effective only if the number specified by 
nn is exceeded for the first destination. 

In order for this function to be provided for a destination, the destination station's 
entry in the terminal table must not specify either a cascade Hst entry or a distri- 
bution Ust entry (that is, do not code a TLIST macro in the terminal table for this 
destination station). 



i 



232 OS/MFT and OS/MVT TCAM Programmer's Guide 



In the case of multiple-buffer headers, a destination must be determined for the 
first header buffer. This can be ensured in one of two ways as the first header and 
the subgroup are designed: 

1. If the destination is specified by the DEST= operand, the FORWARD macro 
must occur sufficiently early in the subgroup that it acts upon the first header 
buffer. 

2. If the destinations are specified in the header rather than by the DEST= 
operand, the first destination must be completely contained within the first 
buffer. For buffered terminals, the first destination must appear in the first 
hardware buffer or the first MCP buffer, whichever is smaller. 

If the second condition is not met, TCAM assumes that an invalid destination has 
been specified and branches to the user exit, if provided. If no user exit is provid- 
ed, or if the first condition is not met, the message is routed to the dead-letter 
queue, or is overlaid and lost, if no dead-letter queue is provided. 



Designing the Message Handler 233 



HOLD 



The HOLD macro 

• suspends transmission to a station; 

• is optional in the inheader, inmessage, and outmessage subgroups. 

HOLD suspends transmission of output messages to a station either for a time 
interval or until t|ie messages are released by a RESMXMIT operator command or 
by an MRELEASE macro issued in an application program (except that resump- 
tion is automatic if this MH is handling logical messages). HOLD may be request- 
ed unconditionally by specifying an error mask of zero or by omitting the mask, 
or conditionally, in which case the error mask specified in the first operand is 
compared to the message error record assigned to the message; if specified errors 
are detected, transmission is suspended. A station that cannot accept messages 
because of the effect of a HOLD macro is said to be intercepted . For a discussion 
of holding, see the section TCAM's Hold/ Release Facility. 

When issued in the outmessage subgroup of an MH handling logical messages, the 
HOLD macro permits the user to transmit a buffer containing an error as soon as 
it is detected. If a transmission interval is specified by HOLD, resumption of 
transmission begins with the block in error (the error block is transmitted 
twice — once when the error is detected, and once when transmission resumes). If 
an interval is not specified, transmission resumes immediately, and the error block 
is transmitted twice. 

An inquiry/response facility is provided by the HOLD/MRELEASE macro 
combination (see TCAM's Inquiry /Response Capabilities in the section Writing 
TC AM -Compatible Application Programs ). The HOLD macro, when issued in 
the inheader subgroup of a Message Handler, suspends transmission of outgoing 
messages to the station entering the message until an MRELEASE macro in an 
application program releases the station. 

By using the macros in combination with TCAM's message priority capability, it is 
possible to ensure that after the intercepted station enters an inquiry the next 
message received by it will be the response from an appUcation program to that 
inquiry. 

If specified in an inheader subgroup, HOLD will supply a return code in register 
15 that can be checked by the next instruction in the MCP. The return codes are: 

X'OO' Sucessful execution. 

X*04' Destination queue is located in main storage with no disk 

backup. 

X*08' Station is already held. 

X'OC Station cannot be held because it is a process entry, cascade 

or distribution list, etc. 

X* 10' Invalid terminal entry address returned by terminal entry 

address finder routine. 

A station whose destination queue is located in main storage with no disk backup 
may not be intercepted; the HOLD macro is ignored in this case. 



{ 



234 OS/MFT and OS/MVT TCAM Programmer's Guide 



In the inheader subgroup, suspension of transmission begins with the message that 
causes the HOLD macro to execute. Otherwise, suspension begins with the 
message following the one that causes the HOLD macro to execute (since the 
outmessage subgroup does not execute until after the message has been sent). 
However, when the station is released, the message that caused HOLD to execute 
is retranmitted, unless HOLD was executed in the inheader subgroup and the 
message was routed to another station. 

If an initiate mode message is sent to a held terminal, the message will revert to 
standard transmission (rather than initiate transmission). However, it will be 
queued on the highest-priority queue and be transmitted normally thereafter. 

If the HOLD macro is executed in the outmessage subgroup for a lock response, 
the lock is not broken, the terminal is not held, and the message will be retransmit- 
ted immediately (that is, it will be sent twice). This can result in an infinite loop if 
the condition for the HOLD is permanent and the line or terminal is inoperative. 
If a terminal is held by an operator command while in lock mode, or if lock is 
initiated while the terminal is held, all lock responses will be sent as if the terminal 
were not held. No other messages will be sent, however, until the terminal is 
released. 



Name 


Operation 


Operands 


[symbol] 


HOLD 


[mask][,RELEASE][,INTVL=mteger] 
[,CONNECT= JANDh [,LEVEL= JBLK / ] 
)OR ( )MSG( 



symbol 



mask 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X* ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting the operand or specifying an all-zero mask causes unconditional 
execution (unless LEVEL=BLK is specified, which causes conditional execution; 
LEVEL =BLK causes a mask to be generated and the text and selection bits to be 
set in the message error record). 

If queuing is by line and a nonzero mask is specified, the mask must include the 
test for the "terminal inoperative" bit of the message error record. 



RELEASE 



Function: Specifies that transmission to the station is to be suspended until either 
a RESMXMIT operator command is issued for the station, or until an 
MRELEASE macro is issued for the station in an application program. 
Default: See Notes 



Designing the Message Handler 



235 



INTVL=integer 



Format: RELEASE 

Notes: Do not code this operand if this MH handles logical messages (TCAM 
automatically resumes transmission). If logical messages are not being handled by 
this MH, and if this operand is omitted and INTVL= is also omitted, RELEASE is 
assumed; if both RELEASE and INTVL= are coded, RELEASE prevails. 
RELEASE should not be specified if LEVEL =BLK is specified. 



Function: Specifies the number of seconds that transmission to the station is to be 
suspended. 

Default: None. Specification optional. 

Format: Positive integer, either decimal or hexadecimal. If hexadecimal format is 
used, framing X* ' or XLn' ' characters must be specified. 
Maximum: 65535 or a hexadecimal field of two bytes. 

Notes: At the end of the specified period, transmission to the station is automati- 
cally resumed. If this operand i^ omitted and this MH handles physical transmis- 
sions, RELEASE is assumed. If both RELEASE and INTVL= are coded, 
RELEASE prevails. If this MH handles logical messages, TCAM automatically 
resumes transmission after the specified time interval; if this operand is omitted, 
resumption is automatic. 

The INTVL= operand may not be coded if the HOLD macro is to be executed in 
the inheader subgroup. It is ignored for nonswitched and buffered stations during 
mid-batch recovery operations. 



CONNECT=JAND/ 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 



i 



OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 

The TCAM checkpoint/restart facility permits restart of a TCAM system after 
system closedown or failure. If the system fails or is closed down while the station 
is intercepted, when the system is restarted by a warm start or a continuation 
restart (defined in the discussion of the checkpoint/restart facility) the intercep- 
tion will still be in effect, but the INTVL= operand will no longer apply; transmis- 
sion will be suspended until a RESMXMIT operator command or MRELEASE 
macro causes transmission to be resumed. 



LEVEL= J BLK ( 
<1VISG1 



Function: Causes a message containing an error to be retransmitted. 

Default: LEVEL=MSG 

Format: BLKorMSG. 

Notes: This operand is required in any subgroup for which mid-batch recovery is 

desired (see Mid-Batch Recovery in the chapter Using TCAM Service 

Facilities ). Use of this operand requires that MB=YES be specified on the source 

station's TERMINAL macro if the source is a nonswitched station (need not be 



236 OS/MFT and OS/MVT TCAM Programmer's Guide 



specified for switched or buffered stations). In an inmessage subgroup, if the 
MB= operand is omitted or if it specifies NO, TCAM cancels the entire incoming 
message. Queuing by terminal is required (see the QBY= operand of the 
TERMINAL macro instruction). 

Mid-batch recovery on output requires that LEVEL=BLK be specified, and the 
HOLD macro specifying this operand must be the first macro in the outmessage 
subgroup (LEVEL=BLK may be specified only once in the subgroup). Multiple 
HOLD macros may be coded in the same outmessage subgroup, but other macros 
may not be coded between HOLD macros. If an error mask is specified when 
LEVEL=BLK is coded, the CONNECT=OR operand must be specified. The 
LEVEL=BLK does not apply to a station entering or accepting messages in lock 
mode. 



t 



Designing the Message Handler 237 



INITIATE 



The INITIATE macro 

• sends message segments to their destination as soon as possible after they are 
received at the destination queue; 

• is optional in an inheader subgroup of an MH. 

The INITIATE macro sends the segments of a message from a destination queue 
to their destination as soon as possible after they are placed on the queue. Usual- 
ly, segments are not sent to the destination until the complete message has been 
placed on the queue. Messages sent by segment are transmitted in initiate mode. 
(For information on when messages destined for stations on the same line are sent 
out relative to each other, see Message Priority and Queuing in the chapter 
Defining Terminal and Line Control Areas .) The destination may be either a 
station represented by a single or group entry in the terminal table, or an applica- 
tion program represented by a process entry in the terminal table. This function 
may be performed conditionally, based on the appearance of a specified character 
in the message header, or it may be performed unconditionally. 

When the first segment of a message processed by INITIATE arrives on a destina- 
tion queue, it is treated as if it were a complete message having the highest priority 
on the queue. If the destination queue was created by a TERMINAL macro, as 
soon as a Une to the destination station is available, TCAM begins sending that 
portion of the message that has arrived at the destination queue. No other mes- 
sage may be sent on the line until this entire message has been transmitted. If the 
destination queue was created by a TPROCESS macro, then each message 
segment is sent to the appUcation program as soon as possible after it is enqueued. f 

If a message is sent to a station for which messages are being held (see the de- 
scription of the HOLD macro), the message reverts to normal transmission mode 
rather than remaining in initiate mode. The message is queued on the highest- 
priority queue and is transmitted to its destination after the station is released for 
accepting messages. Once the station is released from its hold condition, TCAM 
resumes transmitting message segments to the destination using the initiate mode 
as described above. 

The function provided by the INITIATE macro might be used as an early notifica- 
tion to a destination station that a very long message is being received by the 
computer, handled, and routed to that destination. 

If a message has multiple destination codes specified in the header, the initiate 
function is performed only for the first destination. Sending to the remaining 
destinations will occur only after the complete message has been placed on the 
destination queue. The initiate function has no effect on a message originated by 
a buffered station or whose destination is a buffered station (TCAM uses normal 
queuing techniques). 

If static deallocation of buffers is specified (that is, if the PCI= operand of the 
line group DCB macro is coded PCI=N and the incoming message contains no 
EOB or ETB control characters), INITIATE gives the message a priority higher 
than that of any other message on the destination queue. 

Messages being sent using initiate mode must fit in the buffers initially allocated 1 

by the BUFOUT= operand of the line group DCB macro when the PCI= operand 



238 OS/MFT and OS/MVT TCAM Programmer's Guide 



specifies N or R. If the message can not fit in these buffers, the last byte that does 
fit is considered to be the last byte of the message. 



Name 


Operation 


Operands 


[symbol] 


INITIATE 


[conchars[,BLANK= (char ]]] 

Iyes) 



symbol 



conchars 



(YES 



Function: Name of the macro. 

Default: None. Specif ication optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field to be acted upon, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn* ' characters. 

Notes: If this operand is omitted, the initiate function is performed unconditional- 
ly. If the next field in the header does not match this operand, the function is not 
performed. 



Function: Specifies whether an EBCDIC blank or another character is to be ignored 
when encountered in the character string in the message header being compared to 
the string specified by the conchars operand, or whether blanks are to be part of 
the header string when encountered in it. If EBCDIC blanks are to be counted as 
part of the header string, this operand also specifies whether some other hexadeci- 
mal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 



Designing the Message Handler 239 



NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Example: 

INITIATE C £' 

causes the INITIATE function to be executed whenever the & character appears 
as the next nonblank character in the message header. 

In the case of multisegment headers the initiate function must apply to the first 
segment of the message. This is ensured by designing the message header so that 
the control characters appear in the first segment. 



240 OS/MFT and OS/MVT TCAM Programmer's Guide 



LOCK 



The LOCK macro 



• connects one station on a line to an application program to await the response 
to an inquiry message entered by the station; 

• holds the connection for a single message or for an extended period; 

• is optional in an inheader subgroup (and not permitted in any other); 

• is required for audio terminals. 

• is suggested for a 3735 attached to a switched line. 

LOCK keeps the connection between a station and an application program, as 
specified in a message header or by a FORWARD macro, for a period of time not 
less than the duration of a message and its response. A station connected in this 
manner is said to be in lock mode . The appUcation program to which a station is 
locked depends upon the destination specified either in the header or by a 
FORWARD macro. If the destination is not an application program, the station 
is not placed in lock mode. 

LOCK does not execute if the station that entered the message being handled is a 
buffered station whose TERMINAL macro specified a buffer delay (by the 
BFDELAY= operand). In this case, a return code of X*00000004' is passed in 
register 15 by TCAM's lock routine. 

The use of this macro with logical messages is restricted to an incoming logical 
message formed by blocking two or more incoming physical transmissions (see 
Handling Logical Messages in this chapter). 

For a description of the lock function, see TCAM's Inquiry /Response Facilities 
in the chapter Writing TC AM -Compatible Application Programs . 

LOCK has the following format: 



Name 


Operation 


Operands 


[symbol] 


LOCK 


(extend \ [,conchars [,BLANK=( YES )]] 

(message/ {^^ \ 

( char ) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



(extend 1 

|MESSAGEj 



Function: Specifies the type of lock mode required. 

Default: MESSAGE 

Format: EXTEND or MESSAGE. 

Notes: EXTEND specifies that the station transmitting the message is to be 

placed in lock mode until it has no more messages to transmit or until an 

UNLOCK macro is executed. 



Designing the Message Handler 241 



conchars 



MESSAGE specifies that the station transmitting the message is to be placed in 
lock mode for the duration of the message and its response, and that the Une is to 
be freed once the response has been sent. 



Function: Specifies the character or character string that, if found in the header as 

the next nonblank field, causes execution of the function. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with C* ' or CLn' ' 

characters. If hexadecimal format is used, the string must be framed with X* ' or 

XLn* ' characters. 

Notes: If this operand is omitted, the lock function is performed unconditionally. 

If the next field in the header does not match this operand, the function is not 

performed. 

For a station in extended lock mode, control characters are meaningful only for 
the header of the message being processed at the time the station is placed in lock 
mode. The LOCK macro does not examine headers for control characters in 
messages entered by a station already in extended lock mode. 



BLANK=(YES 

NO 
'char 



Function: Indicates whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header that is being compared 
to the string specified by the conchars operand, or whether blanks are to be part 
of the header string when encountered in it. If EBCDIC blanks are to be counted 
as part of the header string, this operand also specifies whether some other 
hexadecimal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 

Notes: This operand is ignored unless the conchars operand is also specified. YES 
specifies that the EBCDIC blank character (X*40') is to be ignored by this macro 
whenever it is encountered in the header character string being checked against 
the control character string specified by the conchars operand. For example, if 
BLANK= YES and an eight-byte field in the header is being checked by this 
macro, a blank appearing in the fifth byte of the field will be ignored and the sixth 
through ninth bytes will be considered to be the last four bytes of the field 
(assuming that no blanks are coded in the sixth through ninth bytes). 



/I 
4 



NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 



char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 



{ 



242 OS/MFT and OS/MVT TCAM Programmer's Guide 



encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Note: For a station in extended lock mode, control characters are meaning- 
ful only in the header of the message being processed at the time that the 
station is placed in lock mode. The LOCK macro does not examine the 
headers for control characters in messages entered by a station already in 
extended lock mode. 



Designing the Message Handler 243 



LOCOPT 



symbol 



opfield 



The LOCOPT macro 

• provides access to fields in the option table; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups 
(and not permitted in any other). 

LOCOPT enables the user to obtain the address of any option field for the 
appropriate terminal table entry. The address of the desired field or a not-found 
indicator is placed in a user-specified register. A user-written routine may then 
examine and modify the contents of the option field. If specified in the incoming 
group, LOCOPT locates option fields for the originating station; if specified in the 
outgoing group, LOCOPT locates option fields for the destination station. If 
specified in an MH handling messages to or from an application program, 
LOCOPT locates the option fields in the process entry for the queue to which the 
GET or READ is directed (if LOCOPT is issued in the outgoing group), or the 
fields in the process entry for the queue to which the PUT or WRITE is directed 
(if LOCOPT is issued in the incoming group). LOCOPT may be used only for 
option fields for stations or application programs using the MH in which 
LOCOPT is issued. 



Name 


Operation 


Operands 


[symbol] 


LOCOPT 


opfield, i (register) ) 
1(15) f 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the option field whose address is desired. 
Default: None. This operand must be specified. 

Format: Must be the name of an option field as defined by an OPTION macro. 
Notes: If the option field is not found, LOCOPT does not execute, a X*04' return 
code is set in register 15, and the specified register will contain a XTF'. If the 
default register 15 is used and the option field address cannot be located, 
register 15 will contain a fuUword of zeros on return. 



I (register) \ 

(05) S 



Function: Specifies the register into which the address of the desired option field is 

to be placed. 

Default: (15) 

Format: A decimal register 2 through 11, or 15, enclosed in parentheses. 



i 



244 OS/MFT and OS/MVT TCAM Programmer's Guide 



LOG 



The LOG macro 

• enables the user to log complete messages or message segments; 

• is optional in any subgroup of an MH. 

LOG enables the user to maintain a record of incoming or outgoing message 
traffic on a sequential medium. Message segments or full messages, as determined 
by the placement of LOG macros in an MH, are placed on an output device. If 
logging is for both message segments and complete messages in the same MCP, a 
data control block must be provided for each function. The various types of logs, 
and the corresponding MH subgroups in which LOG appears are: 

1. Either entire incoming physical transmissions, individual logical messages, or 
portions of individual logical messages (inblock), 

2. Incoming header segments only (inheader), 

3. All incoming segments (inbuffer), 

4. Complete incoming messages (inmessage), 

5. Outgoing header segments only (outheader), 

6. All outgoing segments (outbuffer), 

7. Complete outgoing messages (outmessage). 

When LOG is specified in an inblock subgroup, its position relative to the 
SETEOM macro determines what is logged. If LOG appears before SETEOM, 
TCAM logs the entire incoming physical transmission by segment. If LOG 
appears after SETEOM, either individual logical messages or portions of individu- 
al logical messages are logged, depending on whether deblocking or blocking 
operations are being performed. For deblocking operations, individual logical 
messages are logged (requires that PROCESS = YES be specified on SETEOM). 
For blocking operations, portions of individual logical messages are logged 
(requires that PROCESS = NO be specified on SETEOM). 

When LOG is specified in an inbuffer or outbuffer subgroup, segments are logged 
in the sequence in which they are handled by the Message Handler. In this case, 
segments of different multisegment messages handled at about the same time are 
likely to be intermixed on the logging medium. When segments are logged, their 
buffer prefixes are logged with them. The 12-byte control area connected with 
each buffer unit is not logged. 

LOG may appear at any point in an MH subgroup in which it is used. However, 
the results of any alteration of segments or messages by macros preceding LOG in 
the subgroup will appear in the log. For example, if LOG is preceded by 
DATETIME, a logged header segment will contain the date or time, as specified in 
DATETIME, depending on the location of the date and time in a multisegment 
message. 

LOG may be specified in any subgroup of an MH and may be used more than 
once in a subgroup if desired. The message log may be maintained on any avail- 
able output medium. The user must supply, define, and open the message log data 
sets. For each log data set used to record complete messages, a logtype entry in 
the terminal table must be defined by a LOGTYPE macro (this is not necessary if 
only segments are logged). For information on specifying the message log data 
set, see the chapter Defining the MCP Data Sets . 



Designing the Message Handler 245 



symbol 



When logging segments after a FORWARD macro with multiple destinations, the 
last character of the first destination is overlaid with an unprintable character. 
This byte will be restored at the inmessage subgroup and thus will appear if 
messages are logged. 



Name 


Operation 


Operands 


[symbol] 


LOG 


\ dcbname f 
/ typename ) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



dcbname 
typename 



Function: Specifies the name of the data control block or the logtype entry used 

for logging. 

Default: None. This operand must be specified. 

Format: dcbname or typename. dcbname is the name of the data control block 

for the message log data set and is used if the macro is specified in the inheader, 

inbuffer, outheader or outbuffer subgroup, typename is the name of a logtype 

entry in the terminal table and is used if the macro is specified in the inmessage or 

outmessage subgroup. 

Notes: If dcbname is specified and does not match the name of a vaHd data 

control block, or if typename is specified and does not match the name of a 

logtype entry in the terminal table, the LOG macro does not execute, and a return 

code of X'04' is set in the low-order byte of register 15. 



i 



246 OS/MFT and OS/MVT TCAM Programmer's Guide 



MHGET 



The MHGET macro 



• transfers the contents of the current buffer into a user specified work area or; 

• gives the user the address of the data in the current buffer. 

MHGET may be issued in the inheader or inbuffer subgroup of an MH or in 
serially reusable, user- written open or closed subroutines called in those sub- 
groups. The work area is a part of the MH or the called subroutine and should not 
be confused with an appUcation program work area. MHGET does not affect or 
depend on any functional macros used in the MH or subroutine. Therefore, any 
order of functional macros and MHGET will work. MHGET may be specified 
either to return the address of the first data character in the buffer or to move the 
entire data contents of the buffer into a user-specified work area. The amount of 
data moved will be the entire message or as much of the message as will fit into 
the user-specified work area. The MHGET macro will move data from multiple 
buffers into the work area consecutively, if the length of the data previously 
moved in is left in the DATLEN field of the work area prefix. If the work area is 
to contain only the data from a single buffer, the DATLEN field should be zeroed 
by the user before issuing the MHGET macro. 

The format of the work area is: 



WKLEN 
1 


DATLEN 

2 3 


PRFSTAT 

4 


UNRES 

5 


DATA 
6-n 



Bytes Field 

Name 



Description 



- 1 WKLEN 



User-supplied data length of the work area (does 
not include the six-byte work area prefix length). 



2 - 3 DATLEN 



Length of data moved, supplied by MHGET on return 
to the user. The user must zero this field before 
issuing a single-buffer MHGET or the first MHGET 
of a series of multiple-buffer MHGETs. For the 
second and subsequent MHGETs, when moving the data 
from multiple buffers consecutively into a single 
work area, this field must contain the data length 
put there by the previous MHGET. 



PRFSTAT 



The status byte from the buffer prefix indicating: 



X'OO' Header lost 

X'Or Text lost 

X'OT Header not lost 

X'03' Text (not header) not lost 

X'08' Duplicate header 



> 



5 UNRES 

6-n Data 



The number of unused reserve characters. 



The first to nth data characters in the buffer. 



Designing the Message Handler 247 



MHGET will supply the following return codes in register 1 5 

00 MHGET successful - no errors 

04 Data moved; work area too small; data truncated 

08 TCAM not in system 

OC Empty buffer-no user processing permitted 

MHGET has the following format: 



Name 


Operation 


Operands 


[symbol] 


MHGET 


(W0RK= jregister)) [,RESERVES= rYES )] 
) \name jV |NO j 
pEG=f(register)) I 
V (name j / 



symbol 



WORK=((registerA 
(^ name f 



REG= 



Reregister) 1 
(^ name j 



RESERVES=JYES> 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Points to the user-supplied work area. 

Default: None, (register) or name must be specified. 

Format: ( register ) may be the actual register number, name is the name of a 

work area or may be an equated name of a register. Registers 2 through 12 may 

be used. 



Function: Returns the address of the first data character in the buffer in the 
specified register. The specified register is the lower of a pair of consecutive 
registers. The next higher register will contain the following: 

byte Zero 

byte 1 Buffer status (PRFSTAT 1 ) 

bytes 2-3 Length of the data in the buffer 

Default: None. Must be specified if WORK= operand is not specified. 

Format: ( register ) may be the actual register number. 

name may be an equated name of a register. Registers 2 through 1 1 may be used. 

Function: Move unused reserve spaces into the work area in front of the data. The 
number unused will be put into the UNRES field of the work area header. 
Default: No. 
Format: RESERVES= YES or RESERVES=NO. 






i 



248 OS/MFT and OS/MVT TCAM Programmer's Guide 



MHPUT 



The MHPUT macro 



• transfers the contents of a user-specified work area into the current buffer; 

• resets the scan pointer to the beginning of data in the buffer. 

MHPUT may be issued in the inheader or inbuf f er subgroup of an MH or in 
serially reusable, user- written open or closed subroutines called in those sub- 
groups. MHPUT will transfer whatever is in the user-specified work area into the 
current buffer leaving room for the unused DCB or user-specified reserve charac- 
ters. Up to 65,535 (XTFFF') characters may be written, and the routine will set 
up the maximum number of units per buffer to contain the data. Care should be 
taken that data in the header that subsequent functional macros will need is not 
destroyed or overlaid by execution of the MHPUT macro. Since MHPUT sets the 
scan pointer to the beginning of data in the buffer, before issuing a macro that 
uses the scan pointer, the user should be certain that the scan pointer is properly 
set for that macro. If these precautions are observed, MHPUT does not affect or 
depend on any functional macros, any order of functional macros, and MHPUT 
will work. If PCI=A and EOB checking are used in conjunction with 
MHGET and an input data error occurs, it is possible that some of the data may 
be processed before it is known to be bad. If MHPUT is also unused, it is possible 
that data processed prior to EOB checking may be destoryed by the error recovery 
procedures. These two conditions will be avoided if PCI=X is coded and mid-batch 
recovery is not used. 

Note: The MH prefix of MHGET and MHPUT specifies that the macros 
are to be used in a message handler as opposed to GET and PUT macros 
for an application program. The function of MHGET is to transfer the 
contents of the current buffer into a user specified work area. The function 
of MHPUT is to transfer the contents of a user specified work area into the 
current buffer. The implication is that these macros may be used to perform 
intermediate operations on messages before they are passed on to an applica- 
tion program or to an output destination buffer. The flow might be 



MHGET 



MHGET 



process or process 

MHPUT FORWARD 

The format of the work area is: 



Unused 
1 


DATLEN 

2 3 


Reserved 
4 5 


Data 
6-n 



Bytes 



Field 
Name 



Description 



0- 1 



Unused and unchanged by MHPUT 



Designing the Message Handler 249 



2-3 DATLEN Length of the user-supplied data starting at the 

first position of the data field of the work area. 
Maximum data length can be 65,535 (XTFFF'). 

4-5 Reserved 

6 - n Data User data to be written (MHPUT). 

MHPUT will supply the following return codes in register 15: 

00 MHPUT successful 

04 MHPUT could not allocate enough units; data is truncated. 
This return code is also set when the number of units per 
buffer has reached the maximum. 

08 TCAM not in the system 

10 Length of work area not initiahzed. 

MHPUT has the following format: 



Name 


Operation 


Operands 


[sym-bol] 


MHPUT 


WORK=((register^)[,RESERVE=value] 
( name j 



symbol 



WORK=J(register)) 
I name j 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Provides the name or address of the user's work area. 

Default: None, (register) or name must be specified. 

Format: (register) may be the actual register number, name is the name of a work 

area or may be the equated name of a register. Registers 2 through 12 may be 

used. 



( 



250 OS/MFT and OS/MVT TCAM Programmer's Guide 



RESERVE=value 

Function: Allows the user to specify the reserve count. 
Default: None. Specification optional. 
Format: Unframed decimal integers. 
Maximum: 221 

Notes: When this operand is not specified, MHPUT begins transferring the data 
into the header buffer starting at the first position following the unused DCB 
reserves. This operand allows the user to override that specification. If 
RESERVE =0 is specified, MHPUT begins moving data into the buffer beginning 
at the first byte after the buffer prefix. If RESERVE= 1 is specified, MHPUT 
begins moving data into the second byte after the prefix, etc. If the user reserves 
specified are greater than the maximum allowable in the DCB, the maximum 
allowable is used instead of what was specified by this operand and the return 
code X*OC' is placed in register 15. 



Designing the Message Handler 251 



MSGEDIT 



The MSGEDIT macro 

• inserts specified characters at specified locations in a message; 

• deletes specified characters from a message; 

• replaces deleted characters with other characters, or contracts remaining data 
to fill the gap caused by deletion; 

• dynamically allocates buffer units to contain data inserted in message segments; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups, 
and may not be coded in any other subgroup. 

The MSGEDIT macro allows the user to edit incoming and outgoing messages in a 
Message Handler. Each editing operation performed by MSGEDIT falls into one 
of two categories: it is either an insertion or a removal. 

An insert operation is one in which specified characters are inserted at a specified 
point in a message, with no characters being deleted in the operation. The oper- 
ands of MSGEDIT allow characters to be inserted 

• at a single point in a message; 

• at a specified offset from the beginning of each message segment; 

• whenever a certain character string appears in a message; 

• after every n bytes of message data, where fz is a number specified by the user. 

The inserted data may consist of a single character, or a character string, including 
a string of identical characters. If the MSGEDIT macro is issued in an inheader or 
outheader subgroup, the insert operation is performed only for a single segment of 
a message. This is usually the first segment, but may be a subsequent segment if 
the message has a multiple-buffer header and the MSGEDIT macro is issued in a 
portion of the subgroup that is processing header fields in the second or subse- 
quent segments. (The manner in which inheader and outheader subgroups are 
executed for multiple-buffer headers is described in the chapter Designing the 
Message Handler .) If the MSGEDIT macro is issued in an inbuffer or outbuffer 
subgroup, the insert operation is performed for each segment in the message. The 
insert function might be used to add a new destination name to the destination 
field in a message header, or to insert idle characters into a message destined for a 
printer that requires such characters to prevent ''printing on the fly" during a 
carriage-return operation. For other uses, see the examples below. If the insert 
function is for a character string that may cross buffer boundaries, MSGEDIT 
should be coded in the inblock subgroup. 

A remove operation is one in which a specified character string is removed from a 
message. The user may specify that the character string be replaced with another 
character string, or that the remaining data be contracted to fill the gap left by the 
deleted data. The user may remove 

• a single character string; 

• a specified character string whenever it appears; 

• a specified number of bytes of data whenever a certain character string ap- 
pears; 

• the data located in a specified section of a buffer. 

In any of the above cases, the user may replace the deleted data with other data, 
or he may specify that data following the deleted data in a message segment be 
moved left to fill the gap left by the deleted data. If a substituted character string 
is longer or shorter than the deleted character string, TCAM automatically spreads 



{ 



252 OS/MFT and OS/MVT TCAM Programmer's Guide 



or contracts the data remaining in the buffer to ''fit" the new string; buffer units 
are allocated as needed to accommodate the new data. If MSGEDIT is coded in 
an inheader or outheader subgroup, data is removed from only a single header 
segment of a message. If MSGEDIT is coded in an inbuffer or outbuffer sub- 
group, data is removed from all message segments. The remove function might be 
used to delete a destination from the destination field in the message header, to 
substitute one destination name for another in the header, to remove unnecessary 
data from an outward-bound message, or to replace a specified character with a 
logical-record delimiter that is recognized by application-program GET macros. 

If the buffer containing a message segment is not long enough to accommodate 
additional data inserted by a MSGEDIT macro, more buffer units are automatical- 
ly added to the buffer. Because of internal requirements, for insert operations 
MSGEDIT automatically allocates a minimum of one buffer unit before execution. 
This unit, whether it eventually contains data or not, remains with the buffer. 
This fact should be considered when determining the unit count for the MCP. 
The effect of this automatic unit allocation can be diminished by the use of the 
multiple — operand feature of the MSGEDIT macro. Empty units at the end of a 
buffer are automatically deallocated when the buffer is passed to an INMSG or 
OUTMSG macro; deallocated units are returned to the available-unit queue. 

If the remove function is for a character string that may cross buffer boundaries, 
MSGEDIT should be coded in the inblock subgroup. 

Up to 3 1 separate insert and remove operations may be specified by issuing a 
single MSGEDIT macro having up to 31 groups of positional operands. Since any 
operation that can be performed with multiple groups of operands also can be 
performed with a single group, then only one group of operands is allowed in the 
same MSGEDIT macro. Assembler language restrictions on the length of a macro 
operand apply. 

The MSGEDIT macro operand field consists of from one to 3 1 groups of four 
operands each and a single keyword operand that is coded as the last operand of 
the macro. Each group of positional operands is enclosed in parentheses, and 
each specifies a single insert or remove operation (which may, however, entail 
multiple insertions or deletions). If the user wishes to perform many insert or 
remove operations on his messages, he may either code a single MSGEDIT macro 
having many groups, or he may code several MSGEDIT macros, each performing 
one or two insert or remove operations. 

A single MSGEDIT macro with five groups executes more rapidly than would five 
MSGEDIT macros, each having one of the groups. However, certain restrictions 
that apply to a MSGEDIT macro having several groups are not applicable when 
several MSGEDIT macros having one group each are used instead (these restric- 
tions are discussed below in the description of the MSGEDIT operands). Thus, 
the decision of whether to code one MSGEDIT macro or whether to code several 
depends on which is more important — speed of execution or flexibility. 

Each group contains an AT operand, which specifies where, in a buffer, an insert 
or remove operation is to begin. The order in which operations are performed 
depends upon the relative locations of the character strings specified by the AT 
operand in each group. The function specified by the group whose AT operand 
appears first in a particular message segment is performed first for that segment, 
the function specified by the group whose AT operand appears second is per- 
formed second, etc. 



Designing the Message Handler 253 



When multiple groups of positional operands are coded for a MSGEDIT macro, 
rather than multiple MSGEDIT macros each with a single group, data inserted by 
one operation is not considered to be part of the message segment when another 
operation is being performed. For example, if one group caused a B character to 
be inserted after every A character in the message, and another group of the same 
MSGEDIT macro specified that a C character be inserted after every B character 
in the message, no C character would be inserted after a B character that had itself 
been inserted as a result of an A character having been encountered in the mes- 
sage segment by the MSGEDIT macro. 

Insertion or removal of data using a MSGEDIT macro always results in a move- 
ment of data in the buffer. Even when a MSGEDIT macro specifies only a single 
remove operation and the replacement string is equal in length to the character 
string being replaced, movement of data occurs (though in this case the result of 
the data movement would be that the replacement string would be moved into the 
space originally occupied by the deleted string). As a rule, when a MSGEDIT 
macro operates on any data in a buffer, all of the data between the characters 
affected by the first insert or remove operation and the end of the buffer is shifted 
once by MVC instructions issued internally by TCAM. 

When coded in an inblock subgroup, the MSGEDIT macro can be used to remove 
or replace a character string that extends across message segments and buffer 
boundaries. See the description of the inblock subgroup in Structure of the 
Message Handler. 

The MSGEDIT macro has certain Hmitations: 

1. When issued in an inheader or outheader subgroup, MSGEDIT acts only upon 
one header segment of messages having multiple-buffer headers. The segment 
acted upon is the one being processed by the inheader or outheader subgroup at 
the time MSGEDIT is executed. Moreover, a MSGEDIT macro issued in an 
inheader or outheader subgroup assumes that the header occupies the entire 
segment being operated upon. Thus, if a MSGEDIT macro in an inheader 
subgroup .specifies that NYC is to replace BOS whenever the latter character 
string occurs in the header, and if the header ends midway through the first 
message segment, BOS will be replaced if it appears in the second half of the 
segment, even though it is outside of the header. 

2. Any character string in an operand specified in character format rather than as 
hexadecimal data cannot include a comma or a right parenthesis. If the charac- 
ter field requires the use of these characters, the field must be specified in 
hexadecimal format. 

3. The user must beware of performing message editing functions that either add 
or remove data to the left of the scan pointer while he is performing sequential 
processing of header fields. Because the scan pointer is positioned at a particu- 
lar physical location in the buffer, rather than at a particular character, addition 
of data to the left of the scan pointer results in the shifting of the original scan 
pointer to the left. The following example illustrates the possible problem 
resulting from improper placement of a MSGEDIT macro in the Message 
Handler: 

SETSCAN C'X' 

ORIGIN 5 

MSGEDIT ( ( I , C' INSERT ' , 1 ) ) 

FORWARD DEST=5,E0A=* 



{ 



254 OS/MFT and OS/MVT TCAM Programmer's Guide 



After the SETSCAN and the ORIGIN macros are executed, the buffer might look 
like this: 

prefix X TERMA TERMB TERMC * message data 

f 

scan pointer 



After the MSGEDIT macro executes, the buffer looks like this: 

prefix INSERT X TERMA TERMB TERMC * message 

t . 

scan pomter 

When the FORWARD macro executes, the origin (TERMA) will be considered to 
be the first destination (TERMB.) To avoid such problems, the user may follow 
these two guidelines: 

1. Perform as many of the functions of MSGEDIT as possible in an INBUF or 
OUTBUF subgroup rather than in INHDR or OUTHDR. 

2. Perform all functions of MSGEDIT that affect header fields either before all 
sequential processing of header fields begins, or after all sequential processing 
of header fields has been completed. Examples are: 

a. MSGEDIT ( ( I , C ' INSERT ' , 1 ) ) 
SETSCANC'X' 

ORIGINS 

FORWARD DEST=5 , EOA-* 

b. SETSCAN C'X' 
ORIGINS 

FORWARD DEST-S , EOA=* 
MSGEDIT ( ( I , C ' INSERT ' , 1 ) ) 

MSGEDIT moves the scan pointer backwards for the user for one special case. 
This is a remove (or replace) function specifying the scan pointer itself as the TO 
operand. Examples of this are: 

MSGEDIT ( ( R, , 2S , SCAN ) ) 

MSGEDIT ( (R,C' INSERT' ,2S,SCAN) ) 

In these examples, if the remove or replace function results in the deletion of more 
bytes than exist between the scan pointer and the end of data in the buffer after 
the macro executed, the scan pointer would, if not adjusted, erroneously point 
beyond the end of the data in the buffer and prevent any subsequent sequential 
processing. Therefore, in these cases, the scan pointer is moved backward a 
distance equal to: 

a. the length of the data removed,or 

b. the length of data removed less the length of data inserted. 

The user is cautioned that he may have to read the following description several 
times before he understands how to code the macro. Several examples follow the 
macro description. 

MSGEDIT has the following format: 



Name 


Operation 


Operands 


[symbol] 


MSGEDIT 


((groupl),(group2),...)[,BLANK= (NO )] 

<^charj> 

(yes) 



Designing the Message Handler 255 



symbol 



((groupl),(group2),...) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Each group specifies a single insert or remove function. 

Default: None. At least one group must be specified. 

Format: Each group contains (function,data,AT,TO) operands. They must be 

provided in the order shown, enclosed in parentheses, and separated from each 

other by a comma. 

Maximum: A maximum of 31 groups may be coded. 

Notes: Because of the complexity of the macro, the operands are explained 

individually below. 

The structure of each group of positional operands is as follows: 



Function operand 


Data operand 


AT operand 


TO operand 


JR[A][T]( 




characters 
(hexform,n) 

DELIMIT 
CONTRACT 






characters 

offset 

(integer,optfield) 

SCAN 




characters 
offset 

SCAN 
(count) 

m J 


,... 


L- -1 







function operand 
I R[A][T] , 



luiiciiuii vptri 

|r[AMT]| 



Function: Specifies whether an insert or remove function is to be performed and, 

if a remove function, whether the characters delimiting the beginning and the end 

of removal are themselves to be removed. 

Default: None. This operand must be specified. 

Format: I, R, RA, RT, RAT, or RTA. 

Notes: I specifies that an insertion function is to be performed. The data specified 

in the data operand is the data inserted in the message. 



R specifies that a remove function is to be performed; any data specified by the 
AT operand and the TO operand is to be removed from the message and replaced 
with the data specified by the data operand. If no data is specified by the AT 
operand or by the TO operand MSGEDIT removes one byte of data beginning at 
the location currently designated by the scan pointer. If no data is specified by 
the data operand, data that remains in a buffer after deletion is contracted to fill 
the space left by the removed data. 



A specifies that removal is to begin with the first character of the character string 
specified in the AT operand; in this case, if replacement data is specified in the 
data operand, the first byte of replacement data is inserted in the space occupied 
originally by the first byte of the character string specified by the AT operand. If 
A is omitted, removal and replacement begin with the character immediately 



i 



256 OS/MFT and OS/MVT TCAM Programmer's Guide 



data operand 

r characters 

(hexform,ii) 

DELIMIT 

LCONTRACT. 



following the last character in the string specified in the AT operand. If A is 
coded in a group, a character string should be coded as the AT operand; other- 
wise, MSGEDIT removes one byte of data beginning at the location currently 
designated by the scan pointer and proceeds to the next group, if any, to accom- 
pUsh the next insert or remove function. 

T specifies that removal is to end with the last character of the string specified in 
the TO operand; if T is not coded, the character immediately preceding the first 
character of the string specified by the TO operand is the last character removed. 
If T is coded in a group, a character string should be specified as the TO operand; 
otherwise, MSGEDIT removes one byte of data beginning at the location current- 
ly designated by the scan pointer and proceeds to the next group, if any, to 
accomplish the next insert or remove function. 



Function: If this is an insert function, specifies the data to be inserted in the mes- 
sage. If this is a remove function, specifies either the data to replace the charac- 
ters removed from the message or specifies that the data remaining in a buffer 
after deletion is to be contracted to fill the space originally occupied by the 
deleted data. 
Default: CONTRACT 

Format: characters, (hexform,n), DELIMIT, or CONTRACT, characters may be 
one to eight nonblank characters in character or hexadecimal format. If character 
format is used, framing C ' or CLn' ' characters must be used. If hexadecimal 
format is used, framing X' ' or XLn' ' characters must be specified. 

(hexform.n) must be coded within parentheses, hexform is a single character in 
hexadecimal or character format surrounded by framing X' ' or C ' characters, n 
is a decimal integer and must not be framed. 
Maximum: n may be a maximum of one buffer unit. 
Notes: characters in an insert operation specifies the character string to be 
inserted into the message. In a remove operation, characters specifies the charac- 
ter string that is to replace the deleted data. If messages are to be translated, 
inserted characters should be in EBCDIC; if they are not to be translated, inserted 
characters should be in terminal transmission code. 



(hexform,n) specifies that the single character represented by hexform is to be 
inserted the number of times indicated by n . The inserted characters will be 
contiguous; if this is a remove operation, they will replace the deleted data. This 
operand may be used to insert idle characters in outgoing messages. 

DELIMIT is valid only if the function operand specifies a remove function. 
DELIMIT specifies that the character in the RECDEL= operand of the 
TPROCESS macro whose name is entered as the destination of this message is to 
replace the character string delimited by the AT and TO operands. This character 
is recognized by the application program's GET macro as the delimiter of a 
variable-length record. The MSGEDIT macro in which this operand is coded is 
usually located in the outbuffer subgroup of the MH for the appUcation program 
or in the inbuffer subgroup for the line over which the message is received. If 
MSGEDIT is located in an inheader subgroup, only a single header segment is 
scanned for the character to be replaced. The destination queue must be identi- 



Designing the Message Handler 257 



AT operand 
"characters 

offset 

(mteger,opfield) 

LSCAN 



fied by means of a FORWARD macro before the MSGEDIT macro is issued. If 
the destination of this message is not an application program, the MSGEDIT 
group containing DELIMIT does not execute. 

CONTRACT is vahd only if the function operand specifies a remove function. 
CONTRACT specifies that after the appropriate data has been deleted from a 
message segment, succeeding characters in the buffer are to be moved to overlay 
deleted characters. If contraction results in one or more empty units at the end of 
the buffer, these are released when the segment leaves the incoming or outgoing 
group of the MH. 

If the function operand specifies an insert function and if CONTRACT is coded 
(or if the data operand is omitted), this MSGEDIT macro does not execute, and 
control passes to the next instruction in the MH. 



Function: If an insert function is being performed, specifies the location at which 

the insertion is to be made. If a remove function is being performed, specifies the 

location of the beginning of the string to be removed. 

Default: SCAN 

Format: characters, offset, (integer,opfield), or SCAN. 

characters specifies one to eight nonblank characters in either character or hexade- 
cimal format. If character format is used, the string must be framed with C ' or 
CLn' ' characters. If hexadecimal format is used, the string must be framed with 
X' ' or XLn' ' characters, offset is a decimal integer specified without framing 
characters. 



(integer.opfield) must be coded within framing parentheses, integer may be 
specified either in decimal or hexadecimal format. If hexadecimal format is used, 
the value must be coded within framing X* ' or XLn' ' characters, opfield is the 
name of a halfword option field defined by an OPTION macro. 
Maximum: For offset , 65535. For integer , 65535, or a hexadecimal field of two 
bytes. 

Notes: If this is an insert function, characters specifies a string immediately 
following which the data specified in the data operand is to be inserted. If the 
MSGEDIT macro is included in an inheader or outheader subgroup, the specified 
data is inserted each time this string is encountered in the message header. If the 
MSGEDIT macro is issued in an inbuffer or outbuffer subgroup, the specified data 
is inserted each time this string is encountered anywhere in the message. 

If this is a remove function, characters specifies a string that delimits the begin- 
ning of the data to be removed. If the A suboperand of the function operand is 
included, removal begins with the first character of this string; if A is not included, 
removal begins with the character immediately following the last character of this 
string. If A is coded in the function operand and the TO operand is coded (0) or is 
omitted, only the string specified in the AT operand is removed. If the MSGEDIT 
macro is included in an inheader or outheader subgroup, removal occurs each time 
the character string is encountered in the message header. If the macro is issued in 
an inbuffer or outbuffer subgroup, removal occurs each time the character string is 
encountered in the message. 



i 



258 OS/MFT and OS/MVT TCAM Programmer's Guide 



TO operand 
"characters" 
offset 

SCAN 
(count) 

LiO) 



If characters is coded, either characters or (count) should be specified as the TO 
operand. If SCAN is specified as the TO operand, TCAM assumes a count of zero 
has been specified for TO. If an offset is specified for the TO operand, TCAM 
assumes that the offset is a count. 

If characters is coded, the entire string must be located within a single buffer. If 
more than one group of operands is included in this macro, the AT operand for 
each group must be specified as characters , and each character string specified as 
an AT operand must begin with a different character. 

If this is an insert function, offset specifies the number of bytes beyond the buffer 
prefix immediately following which the first character specified in the data oper- 
and is to be inserted. If this is a remove function, offset specifies the number of 
bytes beyond the prefix immediately following which deletion of data is to begin. 

If the MSGEDIT macro is specified in an inheader or outheader subgroup, offset 
applies to a single header segment only, and insertion or deletion of data occurs 
only once. If the macro is coded in an inbuffer or outbuffer subgroup, data is 
inserted or deleted at the specified offset in every segment of the message. If this 
is an insert operation and an offset of 2 is specified, the first character inserted 
will immediately follow the contents of the second byte beyond the buffer prefix. 
If this is a remove function and an offset of 2 is specified, the first byte whose 
contents are removed from a segment will be the third byte beyond the buffer 
prefix. 

(integer,opfield) specifies that the data coded for the data operand is to be inserted 
after every number of bytes specified by integer. If integer is 20, for instance, the 
data specified in the data operand is inserted after every 20 bytes of message. An 
integer greater than 1 may not be specified if the source station (when MSGEDIT 
appears in the inbuffer or inblock subgroup) or the destination station (when 
MSGEDIT appears in an outbuffer subgroup) uses the block checking feature for 
a message. When insertion does occur, however, it occurs in both the header and 
text, opfield is the name of an option field assigned to the origin (if MSGEDIT is 
coded in the incoming group) or to the destination (if MSGEDIT is coded in the 
outgoing group). The option field must be initialized by the OPDATA= operand 
of the TERMINAL or TPROCESS macro (it may be set to a half word of zero). 
(integer, op field) coded as the AT operand has the following restrictions: 

• I must be coded as the function operand; 

• this MSGEDIT macro may be coded in an inbuffer or outbuffer subgroup only; 

• only one group of positional operands may be specified; 

• characters or (hexform^n) must be specified for the data operand. 

SCAN specifies that insertion or deletion is to begin with the character immedi- 
ately following the byte to which the scan pointer is currently pointing (see the 
description of the scan pointer in Z)e5/gAZ/«g the Message Handler). This oper- 
and may be specified only when the macro is issued in an inheader or outheader 
subgroup. 



Function: For remove functions only, specifies the end of the character string to 
be deleted. 



Designing the Message Handler 259 



Default: (0) 

Format: characters, offset, SCAN, (count) or (0). characters specifies a one- to 
eight-byte field in either character or hexadecimal format. If character format is 
used, framing C* ' or CLn' ' characters must be specified. If hexadecimal format is 
used, framing X* ' or XLn' ' characters must be specified, offset specifies a 
decimal integer coded without framing characters, (count) must be coded within 
its framing parentheses and is a decimal integer specified without framing charac- 
ters. 

Maximum: Both offset and (count) have a maximum value of 65535. 
Notes: characters indicates the location of the last character to be deleted. If the 
T suboperand of the function operand is coded, deletion ends with the last charac- 
ter of the string specified here; otherwise, deletion ends with the character imme- 
diately preceding the first character of the string. The entire string must be 
located in the buffer that contains the delimiter specified by the AT operand, since 
deletion must begin and end in the same buffer. If both the AT and the TO 
operand specify character strings, TCAM assumes that the first byte of the TO 
string is to the right of the last byte of the AT string. 

offset specifies an offset from the beginning of the data in a message segment; this 
offset defines the end of the string to be deleted in this operation. If the offset is 
20, for instance, the character occupying the twentieth byte from the beginning of 
data in the buffer is the last character deleted. The offset must specify a byte that 
is in the same buffer as, and either in the same position as or to the right of the 
first byte of data removed (as specified by the AT operand); each deletion must 
begin and end in the same buffer. If the offset specified by the TO operand is 
identical with the offset specified by the AT operand, the single character located 
at this offset is removed. If the offset is beyond the end of the buffer, data will be 
deleted to the end of the buffer. 

If this MSGEDIT macro is specified in an inheader or outheader subgroup, offset 
applies to a single header segment only and deletion occurs only once. If the 
macro is coded in an inbuffer or outbuffer subgroup, data is deleted from each 
segment. 

SCAN specifies that the character indicated by the current position of the scan 
pointer is to be the last character deleted in this remove operation. This operand 
may be coded only in a MSGEDIT macro issued in an inheader or outheader 
subgroup. If SCAN is coded for both the AT and the TO operand, and R is 
specified in the function operand, the single character located at the current 
position of the scan pointer is deleted. 

(count) and its default value (0) specify the number of bytes of data to be deleted, 
starting with the byte immediately following the AT operand. If the AT delimiter 
is a character string and if A is coded in the function operand, the amount of data 
removed is equal to the sum of the number of characters in the AT delimiter string 
plus the number of bytes specified by (count) . If the integer specified by (count) 
is greater than the number of bytes between the AT delimiter and the end of the 
buffer, all characters between the AT delimiter and the end of the buffer are 
deleted. A count of zero indicates that no data is to be deleted (except for the 
characters in the AT delimiter if A is coded in the function operand); if the TO 
operand is omitted, a count of is assumed. If A is coded in the function operand 
and a string is coded in the AT operand, the string is removed each time it is 
encountered if (0) is coded or if no TO operand is specified. 



i 



260 OS/MFT and OS/MVT TCAM Programmer's Guide 



BLANK=rchar 

/yes 



Function: This operand specifies whether EBCDIC blank characters are to be 
ignored when encountered in searching the message for a field, or whether blanks 
are to be considered part of the field when encountered. If EBCDIC blanks are to 
be counted when found, this operand also specifies whether some other hexadeci- 
mal character is to be ignored when encountered in searching the message for a 
field. 

Defauli: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: YES specifies that the EBCDIC blank character (X'40') is to be ignored 
by this macro whenever it is encountered in a message. For example, if 
BLANK=YES is coded and an eight-byte field is being acted upon by this macro, 
a blank appearing in the fifth will be ignored and the sixth through ninth bytes will 
be considered to be the last four bytes of the field (assuming that no blanks are 
coded in the sixth through ninth bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the message. 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header. That is, the macro automatically 
skips over the character without checking it. If BLANK = char is coded and char 
is not the EBCDIC blank, the EBCDIC blank is treated Hke any other character. 

With one exception (when both the AT and the TO operands are coded as or with 
SCAN), the first byte of a string of data to be removed, as determined by the AT 
operand, must be to the left of, or in the same position as, the last byte of the 
string of data to be removed, as determined by the TO operand. See the following 
examples. 

The first character in a character string to be deleted, as specified by the AT 
operand, must not be to the right of the last character of the character string, as 
specified by the TO operand. If both operands specify the same byte, that byte 
only is removed. As an example, consider the following initial portion of a buffer, 
with the scan pointer located at D: 



N Y C D R A L 



data 



1 



beginning SCAN 
of data PTR 

A MSGEDIT macro coded 

MSGEDIT ( ( R,CL3'B0S' , SCAN, 4 ) ) 
would result in the character D being replaced with the string BOS in the buffer. 
A MSGEDIT macro coded 



Designing the Message Handler 261 



MSGEDIT ( (R,CL3'B0S' ,CL1 'D' ,CL3'RAL' ) ) 

would result in BOS inserted after D; this macro says to remove the character (| 

between D and R and replace it with BOS. Since there is no character between D 
and R, none is removed, but BOS is still inserted. 

Examples 1 : 

MSGEDIT is a complex macro, capable of performing many functions. In this 
section, some of the more common functions of MSGEDIT are discussed and 
illustrated with examples. 

Insertion of a single character string after a specified field in a header buffer: The 
following MSGEDIT macro might be coded in an inheader subgroup to add the 
destination RAL to the Hst of destinations specified in the message header. 
Assume that the last destination specified in the header is NYC, and that 
DEST=(3) is coded in the FORWARD macro. 

EDIT1 MSGEDIT ( ( I,CL3'RAL' ,CL3'NYC' ) ) 

Note that only the function, data, and AT operands are coded for this macro; the 
TO operand must not be coded for an insert operation. 

Example 2: 

Insertion of a character string after every 50 bytes of message data: The following 
MSGEDIT macro might be coded in the outbuffer subgroup of a Message Handler 
assigned to.an apphcation program to cause the EBCDIC Z character (specified as 
a record delimiter by the RECDEL= operand of the TPROCESS macro creating 
the process entry specified as the destination of the message) to be inserted after /^ 

every 50 bytes of message data. I 

EDIT2 MSGEDIT ( ( I , C ' Z \ ( 50 , EDITOPT ) ) ) 

Note that no TO operand is coded and that only one group is specified. 
EDITOPT is the name of a halfword option field created by an OPTION macro 
and initialized with zeros by the OPDATA= operand of the TPROCESS macro 
creating the process entry specified as the destination of this message. 

Example 3: 

Replacement of one character string in a message with another character string: 
The following MSGEDIT macro is coded in the inheader subgroup; it causes the 
character string BOS to be replaced with the character string OMAHA wherever 
the former string appears in the first segment of the message (remember, however, 
that the entire character string BOS must occur in the segment in order for 
MSGEDIT to operate on it). If a buffer is not long enough to accommodate the 
longer character string, TCAM will automatically allocate extra units to the buffer 
as needed. 

EDIT3 MSGEDIT ( ( RA, CL5 ' OMAHA ' ,CL3'B0S' ) ) 

Note that no TO operand is coded. The A in the function operand specifies that 
the AT character string is to be deleted and that the O in OMAHA is to be 
positioned at the location occupied by the B in BOS. If the TO operand had been 
coded BOS, all data in the segment between the first BOS and a second BOS g 

would be deleted. If the segment contained no second BOS, the remove operation 1 



262 OS/MFT and OS/MVT TCAM Programmer's Guide 



would not take place; the macro would not execute, and control would pass to the 
next macro. 

Example 4: 

Insertion and replacement: A single MSGEDIT macro might be issued in an 
inheader subgroup to accomplish the two editing functions described above. This 
macro would cause RAL to be inserted after each NYC in the first segment, and 
would also cause BOS to be replaced with OMAHA each time BOS appeared in 
the first segment. 

EDIT4 MSGEDIT ( ( I , CL3 ' RAL ' , CL3 ' NYC ' ) , 
( RA , CL5 ' OMAHA ' , CL3 ' BOS ' ) ) 

Example 5: 

Deletion and contraction: The following MSGEDIT macro might be issued in the 
inheader or outheader subgroup. It causes the ten bytes immediately following the 
current position of the scan pointer to be deleted; all data following the deleted 
ten bytes in the first message segment is shifted to the left ten spaces to fill in the 
space occupied by the deleted data. The shift may result in an empty unit at the 
end of this buffer; empty units are dynamically deallocated and returned to the 
available unit queue when the buffer leaves the MH group. 

EDITS MSGEDIT ( ( R, , , ( 1 ) ) ) 

Note that the data and AT operands were not coded, since their default values are 
CONTRACT and SCAN, respectively. Figure 20 illustrates how a single buffer 
containing an entire message might look before and after this macro was executed. 
Assume that the units are 64 bytes long, that the buffer consists of two units, and 
that the second unit contains only six bytes of data before the MSGEDIT macro is 
executed. Assume also that all of the ten bytes immediately following the position 
of the scan pointer contain meaningful data (none of the bytes contain blanks). 
Notice that after the deletion was made, all data following the deleted characters 
was moved ten bytes to the left; as a result the second unit contains no meaningful 
data after the remove operation. 

Example 6: 

Insertion of idle characters: The following macro, when coded in an inbuffer or 
outbuffer subgroup, causes 13 EBCDIC idle characters (X'17') to be inserted 
whenever a period is encountered in a message. 

EDIT6 MSGEDIT ( ( I , ( X ' 1 7 ' , 1 3 ) , CL1 ' . ' ) ) 

Example 7: 

Insertion of a record delimiter: The following macro, when coded in an inbuffer 
or outbuffer subgroup, causes the logical record delimiter X to be substituted for 
the character D wherever the latter character appears in a message. The X 
delimiting character, which would be coded in the RECDEL= operand of a 
TPROCESS macro, is considered by a GET command issued by an application 
program to be the delimiter of a logical record. 

EDIT7 MSGEDIT ( ( RA, DELIMIT, CL1 'D' ) ) 

Example 8: 

Miscellaneous examples: The following MSGEDIT macro, when coded in an 
inbuffer or outbuffer subgroup, causes the character string OUT and the ten 



Designing the Message Handler 263 



Buffer before lO-byte deletion of data ; 





































Unit #1 




^12 byte 


5 




te prefix - 




N 


Y 


C 


iiiO Bytes nl 

-nkB-data to be44iiiij 

deleted Hil 

: :::::: 


B 


O 


S 






G>ntro 


1 area 












A 

Scan Pointer 


Unit *2 






^ 12 byte ^ 


3 


5 


/ 


* 


* 


* 


iz/ 


^ "empty" 










control area 









Buffer after deletion and contraction of data: 



Unit #1 



^12 byte _^ 




N 


Y 


C 


B 


O 


S 


■^ — 14 bytes data -^ 


3 


5 


1 


* 


* 


* 


.^-4 empty bytes-^ 


control area 










Scan Pointer . , . j« 

Unit *2 






^12 byte ^ 






-6( 








control area 









Figure 20. Deletion of Data from a Message Segment followed by Contraction of the Segment; KEYLEN=60 and BUFSIZE= 120 

characters immediately following OUT to be removed from a message segment 
wherever OUT appears in a segment. Data following the 13 deleted characters is 
moved to the left to fill the gap caused by the deletion. EBCDIC blanks are 
counted as characters in this example. 

EDITS MSGEDIT ( ( RA, CONTRACT , CL3 ' OUT ' ,( 10 ) ) ) , BLANK=NO 

The following MSGEDIT macro, when coded in an inbuffer or outbuffer subgroup 
causes the data between every R character and E character to be replaced with the 
character string EPLAC. If the data being deleted occupies less space than the 
replacement string, the data in the buffer is automatically spread out to make 
room for the insertion, and another buffer unit is added to the buffer if necessary. 
If the data being deleted occupies more space than the replacement string, data to 
the right of the replacement string is automatically moved to the left to fill the gap. 

EDIT9 MSGEDIT ( ( R, CL5 ' EPLAC ' ,CL1 'R' ,CL1 'E' ) ) 

The following MSGEDIT macro, coded in an inbuffer or outbuffer subgroup, 
causes the characters occupying the tenth through twentieth bytes of each buffer 
to be deleted, and the remaining data to be shifted left to fill the gap caused by 
deletion. 

EDIT10 MSGEDIT ( (R, ,9,20 ) ) 



The following MSGEDIT macro, coded in an inheader or outheader subgroup, 
causes the character occupying the byte to which the scan pointer is currently 
pointing to be removed; subsequent data in the segment is shifted one byte left to 
fill the gap. Note the defaults. 



i 



264 OS/MFT and OS/MVT TCAM Programmer's Guide 



I 



EDIT1 1 MSGEDIT ( ( R, , , SCAN ) ) 

The following MSGEDIT macro, coded in an outbuffer subgroup, causes three 
EBCDIC SYN control symbols (X'32') to be inserted in each segment, beginning 
at the thirty-first byte. 

EDIT12 MSGEDIT ( ( I , ( X ' 32 ' , 3 ) , 3 1 ) ) 

The following MSGEDIT macro, coded in an inblock, inbuffer, or outbuffer 
subgroup, causes the EBCDIC blank character (X'40') to be replaced by 13 
EBCDIC idle characters (Xn?') wherever a blank occurs (BLANK=NO must be 
specified for this operation). In addition, the character string DOLLARS is 
replaced with the character $ wherever it appears, and two blanks are inserted 
after each period in the message. 

EDIT1 3 MSGEDIT ( ( RA, ( XL1 ' 1 7 ' , 1 3 ) , CLl ' '), * 

(RA,CL1 ' ; '$' , CL7 ' DOLLARS ' ), * 
( I , CL2 ' ' , CL1 ' . • ) ) , BLANK=NO 

When multiple operations are performed by a single MSGEDIT macro, the data 
inserted by insert operations is not considered when remove operations are 
performed. The macro should be in an inblock subgroup if the character string 
^DOLLARS' can extend across buffer boundaries. Thus in the above example, the 
two blanks inserted after each period would not be replaced by 1 3 idle characters 
each. 



Designing the Message Handler 265 



MSGFORM 



The MSGFORM macro 

• puts line-control characters into outgoing messages; 

• removes line-control characters (on a count basis) from incoming messages; 

• permits specification and overriding of blocking factors for outgoing messages; 

• permits variable-length reblocking of records for outgoing messages; 

• indicates whether an outgoing message is to be transmitted in transparent or 
non-transparent mode; 

• may be specified in the inblock and outheader subgroups. 

The MSGFORM macro is optional; it may be included in inblock and outheader 
subgroups only. When coded in an inblock subgroup, MSGFORM must appear 
before any other macro that might cause data movement. The MSGFORM macro 
should be coded in the outheader subgroup of a Message Handler assigned to a 
Hne group, and should not be in the outheader subgroup of the MH for an appli- 
cation program. The MSGFORM macro permits the user to divide his outgoing 
messages into logical blocks of data based on a maximum size or a maximum 
number of subblocks per block. The user specifies blocking factors in the oper- 
ands of the TERMINAL or MSGFORM macro; the blocking factors specified in 
MSGFORM override those specified in TERMINAL. In addition, the blocking 
factor may be defined as a number of variable-length subblocks. If MSGFORM 
specifies blocking factors, TCAM inserts appropriate blocking control characters 
into outgoing messages at the beginning and end of each message and at the 
locations indicated by the TERMINAL or MSGFORM operands. If blocking 
factors are not specified in either the MSGFORM or the TERMINAL macro, the 
EOT line-control character is the only one inserted in messages for start/stop 
terminals, and no line-control characters are inserted in messages to BSC termi- 
nals. No buffer space need be reserved for the characters inserted by 
MSGFORM. MSGFORM inserts EOA, ETX, and EOT characters where needed. 
These and the blocking characters are not inserted at the time MSGFORM is 
executed; rather, the characters are inserted after all executable macros in the 
outgoing group have been executed. When the blocking factor is at a maximum 
number of subblocks per block, the subblock delimiters must be in the data before 
MSGFORM executes. For IBM 2260 (Remote), IBM 2265, and BSC stations, 
STX characters are also inserted. For more information on the line-control 
scheme utilized by TCAM, see Defining Terminal and Line Control Areas . 



MSGFORM has the following format: 



Name 


Operation 


Operands 


[symbol] 


MSGFORM 


[BLOCK=integer] [,SUBBLCK=integer] 

[,COUNT=integer] [,SENDTRP= ( YES, PAD )] 

<YES,NOPAD> 
(NO ) 

[,ENDCHAR=subblock delimiter] 



266 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



BLOCK=mteger 



SUBBLCK=integer 



sendtrp= ( yes, pad 

] yes, nopad 
(no 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the number of bytes in each subblock of data for incoming 
and in each block of data for outgoing messages in transparent or non-transparent 
mode. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 
XLn' ' characters must be specified. 
Maximum: 65535 or a hexadecimal field of two bytes. 

Notes: If this operand is not specified for output, the value used is that specified 
by the blocksize suboperand of the NTBLKSZ= operand of the TERMINAL 
macro, or by the TBLKSZ= operand of the TERMINAL macro for the destina- 
tion station. 

When data is to be sent in transparent mode, the number of buffers assigned for 
BUFOUT must be large enough to contain an ETB block. The value is specified 
in the BLOCK= operand of the MSGFORM macro or the TBLKSZ= operand of 
the TERMINAL macro. 

When both the BLOCK= and the ENDCHAR= operands are coded in the 
inblock subgroup of an MH assigned to a Une group, the other operands of the 
MSGFORM macro cannot be coded. 

On input, TCAM inserts an EOB or an ETB line-control character after each 
number of bytes specified by integer . 



Function: Specifies the number of bytes per ITB character for outgoing messages 

in non-transparent mode to BSC stations. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 

XLT ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field. 

Notes: If this operand is not specified, the value used is that specified by the 

subblocksize suboperand of the NTBLKSZ= operand of the TERMINAL macro 

for the destination station. 

TCAM inserts an ITB control character after each number of bytes specified by 
integer . 



Function: Specifies whether this message is to be sent out in transparent mode. 
Default: NO 
Format: YES 

YES, PAD 

YES, NOPAD 

NO 
Notes: YES should not be coded unless the message is being sent to a BSC 



Designing the Message Handler 267 



ENDCHAR=subblock delimiter 



COUNT=mteger 



Station. PAD is a default of YES and indicates that padding with blanks will be 
done to short blocks of data. SENDTRP can be coded YES or YES, PAD. YES, 
NOP AD specifies that no padding is to be done in transparent mode. NO speci- 
fies that the message is sent out in non-transparent mode. Padding or no padding 
applies only to the last block of the message. 



Function: Specifies the characters that terminate a subblock for outgoing mes- 
sages. Specifies the characters to be deleted from incoming messages. 
Default: None. Specification optional. 

Format: Character or hexadecimal. XLn' ' or CLn' ' must be coded as framing 
characters. 
Maximum: 8 bytes. 

Notes: Subblock delimiters, when required, must be in the output data before 
blocking is performed. 

When the ENDCHAR= and the BLOCK= operands are both coded in the 
inblock subgroup of an MH assigned to a Hne group, the other operands of the 
MSGFORM macro cannot be coded. 

When both the ENDCHAR= and the COUNT= operands are coded in the 
outheader subgroup of an MH assigned to a line group, the other operands of the 
MSGFORM macro cannot be coded. 

Since MSGFORM is coded in the outheader subgroup, but is the last macro to 
execute in the outgoing group, the user should code the ENDCHAR string in line 
code. 



Function: Specifies the maximum number of subblock delimiters in the variable- 
length blocks of data to be constructed for output operations. 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' 
characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field. 

Notes: When both the ENDCHAR= and the COUNT= operands are coded in 
the outheader subgroup of an MH assigned to a line group, the other operands of 
the MSGFORM macro cannot be coded. 



268 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



mask 



MSGGEN 



The MSGGEN macro 

• generates an unqueued message; 

• is optional in inmessage and outmessage subgroups; 

• may be issued more than once in a subgroup. 

MSGGEN generates a message if the errors specified by the error mask operand 
match the bits set in the message error record (see Appendix B for a description 
of the message error record). If a zero mask is specified, the message is generated 
unconditionally. The generated message bypasses all normal functions, such as 
MH processing, queuing, logging, and buffer requesting. The MSGGEN macro 
informs the user of an error more rapidly than does the ERRORMSG macro, but 
does not return the header of the message in error, as the latter macro does. 

If MSGGEN is specified in an inmessage subgroup, the generated message, as 
specified by an operand, is sent to the originating station; if specified in an 
outmessage subgroup, the message is sent to the destination station. MSGGEN 
may be specified more than once within a subgroup. 

This macro may be used to generate a message based on an error condition 
detected in a logical message formed by deblocking an incoming physical message. 
Its use requires that the inblock subgroup's SETEOM macro specify 
PROCESS=YES. Logical messages are discussed in Handling Logical Messages 
in this chapter. 



Name 


Operation 


Operands 


[symbol] 


MSGGEN 


[mask], (message ) 
1 fieldnamer 

[,CONNECT=)AND\] 

toR ] 
[,CODE=(tablename H 

Ino f 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (see the description of the message error record in 
Appendix B ). 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X' ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting the operand or an all-zero mask causes unconditional execution. 



Designing the Message Handler 269 



i message ) 
fieldnames 



Function: Specifies the message or the location of the message to be sent to the 

originating or destination station, depending on whether MSGGEN is issued in an 

inmessage or outmessage subgroup, respectively. 

Default: None. This operand must be specified. 

Format: message or fieldname, message is the actual message to be sent, and has 

a maximum length of 24 bytes. It must be framed, either by C \ CLn' ', X' ', or 

XLn' ' framing characters, fieldname is the symbolic name of the field containing 

the message. It must not be specified with framing characters. 

Notes: The message may be specified in EBCDIC and translated as specified by 

the CODE= operand, or it may be specified in line code if no translation is to 

occur. 

The field referred to by fieldname must have as its first byte the hexadecimal 
count equal to the number of bytes in the rest of the field. The maximum number 
of bytes in the message portion of the field is 24. 

All line-control characters, including the EOT, must be coded by the user in his 
message, with the following exceptions: 

• TCAM provides the EOA line-control characters for the IBM 1030, IBM 1050, 
IBM 1060, IBM 2740, 1 15A and 83B3 stations. 

• TCAM provides an EOT character for BSC stations. 

• The user should not insert block-checking characters (EOB) in MSGGEN 
messages directed to a start-stop station. 

If the user inadvertently inserts block-checking characters (for instance, EOB) in 
MSGGEN messages directed to a start-stop station, no checking occurs. For BSC 
stations, the presence of block-checking characters will cause checks to be made. 
Messages sent out by MSGGEN are never transmitted in transparent mode. 



connect=Jand 1 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. OR specifies that the 

macro is to be executed if any bit specified by mask is on in the message error 

record. 



CODE=Jtablename| 



Function: Specifies the type of translation for the generated message. 

Default: None. Specification optional. 

Format: tablename or NO. 

Notes: tablename is specified as described for the TRANS = operand of the line 

group DCB macro. Register notation may not be used. The user may devise and 

specify his own translation table as described for the CODE macro. 

NO specifies that the message is not to be translated. If this operand is omitted, 
the message is translated using the translation table specified in the hne group 



i 



270 OS/MFT and OS/MVT TCAM Programmer's Guide 



DCB for the line. If this operand is omitted and no translation table is specified in 
the line group DCB macro, no translation occurs. 

A message generated by MSGGEN may not be directed to a distribution list or to 
an application program when specified in an inmessage subgroup. 

Note: A premature disconnection on a switched line will prevent the message 
from being returned to the originating station; the message will be lost. 






Designing the Message Handler 271 



i 



i 



MSGLIMIT 



The MSGLIMIT macro 

• limits the number of messages to or from a station during a single transmission 
sequence; 

• is effective only when used with a nonswitched line; 

• is ineffective for buffered stations; 

• is optional in the inblock, inheader, and outheader subgroups of an MH. 

• is ineffective in the outheader subgroup if send priority is specified in the DCB 
macro. 

MSGLIMIT limits the number of messages that can be transmitted to or accepted 
from a single station on a nonswitched line following a positive response to 
invitation or selection. If coded in an inblock subgroup, MSGLIMIT limits 
physical transmission sequences initiated by a station. If coded in an inheader 
subgroup, MSGLIMIT limits the number of messages entered by a station or 
application program during a single transmission sequence; if coded in an out- 
header subgroup, MSGLIMIT limits the number of messages sent to a station or 
appUcation program during a single transmission sequence. For instance, for 
stations that are polled, MSGLIMIT in the inheader subgroup causes the current 
station to cease to be polled once the specified maximum number of messages is 
reached; the next entry is then polled. If no limit is set for polled stations, each 
station is polled until it has no more messages to enter (negative response). 

MSGLIMIT has no effect when used with a switched Une or with buffered stations 
on a nonswitched Une. The MSGLIMIT macro is optional in inheader and out- 
header subgroups. Its use is suggested for IBM 2260 and 2265 terminals; the 
outheader subgroup for these terminals should include a MSGLIMIT macro 
specifying a limit of one message in inquiry appUcations (in order to ensure that a 
response message is not erased before it can be read). For a description of the use 
of MSGLIMIT with a contention terminal, see Transmission Priority for Non- 
switched Contention Stations in the chapter Terminal and Line Control Area 
Definition . 

If a MSGTYPE macro or user code is used to cause MSGLIMIT to be executed 
only for certain types of messages, only those subsequent messages examined by 
the same MSGLIMIT macro will be counted when the limit for a station is being 
determined. If send priority is specified, the MSGLIMIT macro will have no 
effect. When the limit is reached the send priority condition will cause more 
output (if ready) to be sent to the terminal. The send priority will make the effect 
of the MSGLIMIT macro transparent to the user. 



Name 


Operation 


Operands 


[symbol] 


MSGLIMIT 


rinteger)^ 
1 opfieldj 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Designing the Message Handler 273 



{integer | 
opfield i i 

Function: Specifies the number of messages or the location of the number of ^ 

messages that the user wishes to transmit to or receive from each terminal on the 
line. 

Default: None. This operand must be specified. 

Format: integer or opfield. integer may be specified either in decimal or hexade- 
cimal format. If hexadecimal format is specified, framing X' ' or XLn' ' characters 
must be coded, opfield must be the same as the name of a one-byte option field 
defined by an OPTION macro. 

Maximum: For integer, 255 or a one-byte hexadecimal field. 
Notes: If integer is specified, all stations processed bylhis MH are limited to the 
same MSGLIMIT value. If opfield is specified, the option field contains the hmit 
of consecutive message transmissions that is allowed to or from a station. Use of 
this operand allows the message limit specification to be different for each station. 
If the option field cannot be found, MSGLIMIT does not execute, and a return 
code of X'04' is set in the low-order byte of register 15. 



( 



274 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



MSGTYPE 



The MSGTYPE macro 

• controls the path of a header through an MH; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroup); 

• may be used more than once in a subgroup. 

MSGTYPE enables the user to categorize incoming or outgoing messages into two 
or more message types, each of which he processes in a different manner. 

Use of MSGTYPE is optional. Any number of MSGTYPE macros may be issued 
within a subgroup, provided that they all examine the same position in the buffer 
for the message-type characters. Only one field in a header per inheader or 
outheader subgroup may contain message-type characters, and only one sequence 
of code beginning with a MSGTYPE macro is executed in an inheader or out- 
header subgroup for any one incoming or outgoing message. MSGTYPE may be 
used only within inheader and outheader subgroups. 

The use of MSGTYPE is discussed in the Variable Processing within a Message 
Handler section of this chapter. 

MSGTYPE has the following format: 



Name 



[symbol] 



Operation 



MSGTYPE 



Operands 



conchars 
' TABLE=name,EXIT=name 



[,BLANK=/YES 






NO 

f char 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



conchars 



Function: Specifies the character or character string to be compared with the 
message type field in the message header. 

Default: None. Specification optional. The conchars operand cannot be used 
when the TABLE = and EXIT= operands are used. 

Format: One to eight nonblank characters or hexadecimal format. If character 
format is used, the string may be unframed or framed with C* ' or CLn' ' charac- 
ters. If hexadecimal format is used, the string must be framed with X' ' or XLn' ' 
characters. 

Notes: When using the conchars operand, the next nonblank character or charac- 
ter string in the header buffer (after the current setting of the scan pointer) is 
compared with a character or character string specified by conchars . If the 
conchars field matches the field in the header buffer, all instructions between this 
MSGTYPE macro and the next MSGTYPE macro (or the next delimiter, if there 
is not another MSGTYPE macro) are executed. The next MSGTYPE macro is 
not executed, and a branch is made to the next subgroup. If the conchars field 



Designing the Message Handler 275 



TABLE=name 



EXIT=name 



BLANK= ( YES 
JNO 
(char 



does not match the field in the header buffer, the scan pointer is reset to its 
position before the comparison, and control passes to the next MSGTYPE macro 
in the current subgroup, or, if this is the last MSGTYPE macro in the subgroup, to 
the next MH subgroup. 

If the MSGTYPE macro has no operands, the group of instructions that immedi- 
ately follow this MSGTYPE macro will process the message header not processed 
by a preceding MSGTYPE macro with a conchars operand. A MSGTYPE macro 
with no operands may be used only at the last of a series of MSGTYPE macros 
with conchars operands. 

If MSGTYPE macros are used with and without operands, either some message- 
type field should always be specified, or care should be taken, if the field is 
omitted, that the next field cannot match any of the strings specified by the 
conchars or TABLE= operands in the series of MSGTYPE macros. 



Function: Provides the name of the first of a series of one or more TYPETABL 
macros. See the description of the TYPETABL macro. 

Default: None. Specification optional. The conchars operand cannot be used 
when the TABLE= and EXIT= operands are used. 
Format: Must conform to the rules for assembler language symbols. 
Notes: When using the TABLE = operand, the next nonblank character in a 
header buffer (after the current setting of the scan pointer) is compared with a 
table of message-type characters generated by one or more TYPETABL macros, 
and the address of the next subgroup is placed in register 2. If a match is found, 
the scan pointer is moved one position to the right, and a branch is taken to the 
address in the table for that message type. When user processing of the message is 
completed, the user can branch to the next subgroup (BR 2) or to another address 
within the current subgroup. If no match is found in the table, the scan pointer is 
not moved, and a branch is taken to the address specified by the EXIT= operand. 

Since one execution of a MSGTYPE macro (using the TxABLE= operand) exami= 
ines one character in the message-type field of a header buffer, multiple characters 
can be included in the message-type field, and multiple MSGTYPE macros can be 
issued to examine these characters. 



Function: Provides the address to which this MSGTYPE macro will branch if the 

message-type character in the header buffer does not match any entry in the table 

pointed to by the TABLE= operand of this MSGTYPE macro. 

Default: None. Specification required when the TABLE = operand is specified. 

Invalid when the conchars operand is specified. 

Format: Must conform to the rules for assembler language. 

Notes: name is the symbolic address to which this MSGTYPE macro will branch 

on an unequal comparison. 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be considered 
as part of the header string when encountered in it. If EBCDIC blanks are to be 
counted as part of the header string, this operand also specifies whether some 



276 OS/MFT and OS/MVT TCAM Programmer's Guide 



other hexadecimal character is to be ignored when encountered in the header 

string. 

Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 

either character or hexdecimal format. If character format is specified, it may be 

unframed or framed with C ' or CLT ' characters. If hexadecimal format is 

specified, it must be framed with X' ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X*40') is to be ignored by this 

macro whenever it is encountered in the header character string being checked 

against the control character string specified by the conchars operand. For 

example, if BLANK=YES is coded and an eight-byte field in the header is being 

checked by this macro, a blank appearing in the fifth byte of the field will be 

ignored, and the sixth through ninth bytes will be considered to be the last four 

bytes of the field (assuming that no blanks are coded in the sixth through ninth 

bytes). 

NO specifies that the EBCDIC blank character is to be treated Uke any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparision and goes on to check the 
next character in the header. If BLANK = char is coded and char is not the 
EBCDIC blank character, the EBCDIC blank is not ignored by this macro when it 
is encountere4 in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Uke any other character. 

Note: The use of char is invalid when using the TABLE= operand. 

Example: 

The beginning of an MH using MSGTYPE is shown in Figure 21. Type A mes- 
sages are processed and forwarded to terminal NYC, type B to terminal BIX, and 
all others to an application program. 



MHA STARTMH LC=OUT 



LC= must be coded 
for STARTMH 



INHDR 



Delimiter 



SEQUENCE 

ORIGIN 

DATETIME 

COUNTER 



MSGTYPE 



FIELD 



C'A' 



Macro instructions 
executed for all 
header segments 

Count incoming 
segment 

Test for Type A 
messages 



Macro instructions 
executed for all Type 
A messages 



FORWARD 



DEST=CL3*NYC' 



Designing the Message Handler 277 



MSGTYPE 



FORWARD 

MMSGTYPE 

FORWARD 



INMSG 
etc. 



C'B' Test for Type B 

messages 

Macro instructions 
executed for all Type 
B messages 

DEST=CL3'BIX' 

DEST=CL8 ' PROCESSQ ' Macro instruction 

executed for all other 
message types 

Delimiter 



Figure 21. Example of Using MSGTYPE Macro Instruction 

Additional examples: 

1. Message-type field of the header buffer is AC. 





MSGTYPE 


A 


MSGTYPE 


C 


user code 




BR 


NF 


user code 




BR 


MAIN 


TYPETABL 


ATYPE 


TYPETABL 



TABLE=MA1N , EXIT=NF 
TABLE=ATYPE , EXIT=NF 



A,ROUTINE=A 
C,ROUTINE=C 

2. Series of MSGTYPE macros using conchars operands followed by a 
MSGTYPE macro using TABLE= operand. 



MTA 



MTB 



MT1 



MSGTYPE C' ATYPE' 

user code 

MSGTYPE C'BYTYPE' 

user code 

MSGTYPE TABLE=TABLE1 ,EXIT=EXIT1 



If the header message has a message type of ATYPE or BTYPE, the user code 
following the MSGTYPE macro named MTA or MTB will be executed, and a 
branch will be taken to the next MH subgroup. If the message type is not 
ATYPE or BTYPE, the scan pointer is reset to its position before the compari- 
son, and the MSGTYPE macro named MTl will execute as shown in additional 



i 



278 OS/MFT and OS/MVT TCAM Programmer's Guide 



example 1. 

3. MTA MSGTYPE C ' ATYPE ' 

user code 
MTB MSGTYPE 

user code 
MT1 MSGTYPE TABLE=TABLE1 ,EXIT=EXIT1 

If the message type is ATYPE, the MTA user code is executed, and a branch is 
taken to the next MH subgroup. If it is not ATYPE, the scan pointer is reset to 
its position before the comparison, the MTB user code is executed, and a 
branch is taken to the next MH subgroup. 

To get to MTl, the user would have to branch there from either the MTA user 
code or the MTB user code. If a branch to MTl is taken from MTA, the scan 
pointer will be situated at the last position of the message-type field. If a 
branch to MTl is taken from MTB, the scan pointer will be situated at its 
position before the comparison. 



i 



Designing the Message Handler 279 



ORIGIN 



The ORIGIN macro 

• checks the vaUdity of the origin field in a message header; 

• sets a bit in the message error record for the message if the origin field is 
invalid; 

• permits identification of a switched station calling the computer; 

• is optional in the inheader subgroup and is not permitted in any other subgroup. 

The function of the ORIGIN macro depends upon the kind of connection made 
with the station. For nonswitched stations, ORIGIN verifies that the origin field 
in the header contains the symboUc name of the station that was invited to send 
the message (that is, the origin field is compared with the name of the terminal 
table entry for the station that was contacted). If the names are not the same, an 
error flag is set in bit 1 of the message error record for the message. 

For switched stations, ORIGIN both checks the vahdity of the origin field in the 
header and identifies the caUing station to TCAM. Unless the calling station is a 
BSC station that transmits a unique ID sequence upon successfully calling the 
computer, TCAM does not know what station is on the line until an ORIGIN 
macro is issued in the MH. Once an ORIGIN macro is issued, TCAM compares 
the name in the origin field of the message header with the terminal table entries 
for the stations assigned to Unes in the Une group to which the line connecting the 
calling station to the computer is assigned. If a match is found, TCAM assumes 
that the station named in the origin field is the calling station. If no match is 
found, an error flag is set in bit 1 of the message error record for the message. 

Inheader subgroups for switched lines to stations that do not have unique ID 
sequences and that may call the computer and enter messages should include an 
ORIGIN macro, as this is the only means TCAM has of identifying the calling 
station in this situation. 

An inheader subgroup that handles messages entered only by BSC stations having 
unique ID sequence requires no ORIGIN macro. When an ORIGIN macro is 
included in the inheader subgroup that processes header segments entered by such 
a station, the name in the origin field, if valid, takes precedence over the name 
associated with the ID sequence in the invitation Ust; that is, TCAM assumes that 
the station named in the origin field is the station that entered the message. 

For switched stations assigned to a Une for which a TERMINAL macro coded 
UTERM= YES has been issued, the position of ORIGIN in the inheader sub- 
groups determines whether the option fields assigned to the line or those assigned 
to the station will be updated by MH macros when a station calls the computer. 
Inheader macros executed before ORIGIN refer to option fields assigned to the 
line by a TERMINAL macro coded for the line, while macros executed after 
ORIGIN refer to option fields assigned to the station by a TERMINAL macro 
coded for that station. (For a more detailed discussion of the relationship be- 
tween the ORIGIN macro and the TERMINAL macro coded for a line, see 

Coding the Terminal Macro for a Line in Defining Terminal and Line 

Control Areas .) 

If ORIGIN is used with a message having a multiple-buffer header and entered 
from a station on a switched Une, ORIGIN must be executed for the first header 
buffer in order to effectively identify the station. 



( 



280 OS/MFT and OS/MVT TCAM Programmer's Guide 



A CODE macro must be issued before ORIGIN (unless the line code is 
EBCDIC). 

Care must be taken in entering a character string in an origin field in the message 
header to ensure that it matches a terminal table entry. A character string entered 
in lowercase characters from an IBM 2770 station, for example, will not match a 
terminal table entry name that is in uppercase characters. See additional use for 
the ORIGIN macro in Appendix J, Concentrating and Deconcentrating Messages . 



The ORIGIN macro has the following format: 



Name 


Operation 


Operands 


[symbol] 


ORIGIN 


["integer"! 
LXTF' . 



symbol 



[integer] 
X'FF J 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbol (see the symbol 

entry in the Glossary ). 



Function: Specifies the number of characters in the origin field of a message 

header. 

Default: XTF' 

Format: Decimal or hexadecimal. If hexadecimal format is specified, framing X' ' 

or XLT ' characters must be used. 

Maximum: 8 

Notes: If integer is specified, that many characters are considered to be the origin 

field. Embedded blanks are ignored. 

XTF' indicates that the origin field is of variable length. The origin field is 
considered to end at the next blank. 

Note: // an ORIGIN macro determines that the source of a message on a 
nonswitched line is invalid, a return code of XV4' is set. 



Designing the Message Handler 281 



PATH 



The PATH macro 

• alters a path-switch byte, thereby permitting dynamic variation of the path of a 
message through an MH; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups 
(and not permitted in any other subgroup). 

One-byte option fields are used to maintain switches known as path switches . 
These switches are located in option fields defined by OPTION macros. The 
switches must be set initially by the OPDATA= operand of the TERMINAL or 
TPROCESS macro (if the option fields are not initiaUzed, the PATH macro 
provides a return code of X'OO'). The setting of path switches is examined by 
each delimiter macro as the message reaches the subgroup it controls (the user 
specifies by the PATH operand of each delimiter which path-switch bits are to be 
examined). More than one option field may be specified for each station; each 
path-switch byte so defined consists of eight binary switches. 

If any of the binary switches tested by a delimiter is on, the subgroup controlled 
by that delimiter is executed; if none of the binary switches tested is on, control 
passes to the next delimiter. 

The user may specify a character string (consisting of one to eight nonblank 
characters). If this character string appears in the header of a message, the PATH 
macro with that character string sets one or more specified path switches. If no 
character string is specified, the switches are set unconditionally. 

PATH may specify any number between zero and 255, inclusive. The switches 
remain set until reset by a PATH macro specifying the same option field, until 
modified by user code and LOCOPT, or until modified by a DATOPFLD opera- 
tor command. 



The use of PATH is discussed in the Variable Processing within a Message 
Handler section of this chapter. 



Name 


Operation 


Operands 


[symbol] 


PATH 


switch,opfield [, conchars[, BLANK= (yES)]] 

^NO> 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



switch 



Function: Specifies the path switch setting to be made for the byte residing in the 

option field named by the op field operand. 

Default: None. This operand must be specified. 

Format: Decimal or hexadecimal. If hexadecimal format is specified, framing X' 



i 



282 OS/MFT and OS/MVT TCAM Programmer's Guide 



opfield 



conchars 



or XLV ' characters must be used. 
Maximum: 255 or a one-byte hexadecimal field. 

Notes: If is specified, all eight path switches are turned off. If 255 (or XTF') is 
specified, all switches are turned on. 



Function: Specifies the path-switch byte to be operated upon. 

Default: None. This operand must be specified. 

Format: The name of a one-byte field in the option table as defined by an 

OPTION macro. 

Notes: If the option field cannot be found, the path-switch byte is not operated 

upon, and a return code of X'OO' is set in the low-order byte of register 15. 

If PATH is coded in the incoming group of an MH for a line group, the specified 
option field for the station entering the message is operated upon. If PATH is 
coded in the outgoing group of a hne MH, the specified option field for the 
destination station is operated upon. If PATH is coded in the outgoing group of 
an MH assigned to an application program, the option field associated with the 
process queue to which the GET macro is directed is operated upon. If the macro 
is coded in the incoming group of an MH assigned to an application program, the 
option field for the process entry associated with the DCB named in the PUT 
macro is operated upon. 



Function: Specifies the character or character string that, if found in the header as 

the next nonblank field, causes execution of the function. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with O ' or CLn* ' 

characters. If hexadecimal format is used, the string must be framed with X' ' or 

XLn' ' characters. 

Notes: This operand should be coded only in PATH macro issued in an inheader 

or outheader subgroup. 

If this operand is omitted, the PATH function is performed unconditionally. If the 
next field in the header does not match this operand, the function is not per- 
formed. 



BLANK= (char 

/yes 



1^ 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES or NO or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLl* ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. 
YES specifies that the EBCDIC blank character (X*40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 



Designing the Message Handler 283 



against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be ^ 

ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Hke any other character. 

Example: 

Figure 22 shows the outline of an inmessage group of an MH. Messages with A, 
B, or C in an appropriate field are routed through the incoming group by PATH 
macro instructions. The switch settings enable the user to select appropriate 
inbuffer and inmessage subgroups. Message type A passes through the first 
inbuffer subgroup and the second inmessage subgroup, etc. 

Note: In the case of multiple -buffer headers, the entire control-character /^' 

field must appear in the first header segment. '^ 



i 



284 OS/MFT and OS/MVT TCAM Programmer's Guide 



Name 


Operation 


Operands 


Comment 


VARYPATH 


STARTMH 


LC=OUT 


Inheader subgroup executed 




INHDR 

• 




for all messages. 




• 
• 
PATH 


4, SWITCH, C A' 


Sets switch for type A 
messages ( not executed for 




• 




others. ) 





• 
PATH 


2, SWITCH, C'B' 


Sets switch for type B 
messages. 




PATH 

• 


1 ,SWITCH,C'C' 


Sets switch for type C 
messages. 




INBUF 




4, SWITCH 


This inbuffer subgroup is 
executed if switch is 4. 




• 
INBUF 


PATH-( SWITCH, 4 ) 


This inbuffer subgroup is 
executed if switch is 2. 




INBUF 


PATH=( SWITCH, 2 ) 


This inbuffer subgroup is 
executed if switch is 1 . 




INMSG 


PATH=( SWITCH, 3 ) 


This inmessage subgroup is 
executed if switch is 1 or 2 . 




INMSG 


PATH=( SWITCH, 4) 


This inmessage subgroup is 
executed if switch is 4. 




INEND 







Figure 22. Example of Using the PATH Macro Instruction to Vary MH Processing 



Designing the Message Handler 285 



PRIORITY 



The PRIORITY macro 

• specifies priority handling for messages; 

• is optional in an inheader subgroup of the MH; 

• may be used more than once in the subgroup. 

PRIORITY provides handling of outgoing messages according to priority levels. 
The priority level may be entered in the message header by the user, or it may be 
specified by an operand of the PRIORITY macro. The permissible priority levels 
for each station or application program are specified in the TERMINAL or 
TPROCESS macro for that destination. If queuing by Une rather than queuing by 
terminal is specified, the first TERMINAL macro for the line contains the permis- 
sible priority levels for all stations on the line. If subsequent TERMINAL macros 
for the same line specify priority levels, they are ignored. If a message priority is 
requested that is not permitted, the message is assumed to have the next lower 
permissible priority. The PRIORITY macro must be specified within the subgroup 
in the same relative order as the header field on which it acts. 

Absence of the PRIORITY macro causes a priority level of zero to be assigned to 
the messages. 

For more information on message priority, see Message Priority and Queuing in 
Defining Terminal and Line Control Areas. 

TCAM converts the decimal priority levels specified by the LEVEL= operand of 
the TERMINAL or TPROCESS macro to their one-byte hexadecimal equivalents. 
If the priority is specified in a message header, it may occupy a one-byte field and 
should provide the hexadecimal equivalent of a decimal priority level specified by 
the LEVEL= operand of the TERMINAL or TPROCESS macro. For example, if 
PRIORITY is executed after a CODE macro (that is, the message segment has 
been translated from line code to EBCDIC), and if messages entered by a particu- 
lar station may be assigned priorities of 1, 2, A, B, or C on output, the LEVEL= 
operand of the TERMINAL macro for that station should be coded 
LEVEL=(193, 194, 195, 241, 242). Here, 193 is the decimal representation of 
the hexadecimal equivalent of the EBCDIC character A; 241 is the decimal 
representation of the hexadecimal equivalent of the EBCDIC character 1, etc. In 
this case, a message with a line-code character 1 assigned as its priority would be 
higher in priority than a message assigned a line-code character A, B, or C. 

On the other hand, if PRIORITY is executed before a CODE macro, and if the 
messages are being entered by a 1050 station and may be sent with priorities of 1, 
2, A, B, or C, the LEVEL= operand of the TERMINAL macro should be coded 
LEVEL=(2, 4, 226, 228, 231); here 2 is the decimal representation of the 
hexadecimal equivalent of the 1050 line-code character 1; 226 is the decimal 
representation of the hexadecimal equivalent of the 1050 line-code character A, 
etc. In this case, a message with a line-code character A assigned as its priority 
would be higher in priority than a message assigned a Une-code character 1 or 2. 



M 

^ 



i 



286 OS/MFT and OS/MVT TCAM Programmer's Guide 



Name 


Operation 


Operands 


[symbol] 


PRIORITY 


[integer] [ ,conchars[ , BLANK = 


Uhar; 


]] 



symbol 



integer 



conchars 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



Function: Specifies the priority level to be assigned to this message. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: If this operand is omitted, TCAM assumes that the priority level is con- 
tained in the next nonblank byte following the current setting of the scan pointer. 
If the priority level is not one that the TERMINAL or TPROCESS macro speci- 
fies as permissible, the next lower permissible priority is assumed. 



Function: Specifies the character or character string that, if included in the 

message header, causes execution of the PRIORITY macro specifying that string. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with C ' or CLn' ' 

characters. If hexadecimal format is used, the string must be framed with X' ' or 

XLn* ' characters. 

Notes: If this operand is omitted, PRIORITY is specified unconditionally. If the 

control characters do not match, the PRIORITY macro does not execute and 

control passes to the next instruction. 

If this operand is specified, but the integer operand is omitted: 

• The message priority is assumed to be contained in the message header as the 
next nonblank character following control characters. 

• A comma must precede the conchars operand. 



BLANK=(YES 
f char 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLl' ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 



Designing the Message Handler 287 



Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenver it is encountered in the header string being compared to the string 
specified by the conchars operand. That is, the macro automatically skips over 
the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it i$ 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Hke any other character. 

If the integer and conchars operands are omitted, the priority is assumed to be in 
the message header, in the next nonblank character following the current setting 
of the scan pointer. 

In the case of multiple-buffer headers, the priority, if desired, must be determined 
for the first header segment to pass through the inheader subgroup. This can be 
ensured in one of two ways: 

1 . The priority field in the header, if used, must be in the first header segment 
(and for messages from buffered terminals, in the first hardware buffer if the 
hardware buffer is smaller than the MCP buffers), or 

2. The integer operand must be specified to provide the priority, and any control 
characters used to execute the PRIORITY macro must be in the first buffer 
(and for messages from buffered terminals, in the first hardware buffer, if the 
hardware buffer is smaller than the MCP buffers). 

Example: 

The following examples show the various ways message priority may be specified. 
It is assumed that the LEVEL = operand of the TERMINAL macro for the 
destination station is coded LEVEL=(241, 243, 245, 247). 






i 



288 OS/MFT and OS/MVT TCAM Programmer's Guide 



PRIORITY Macro 


Header Fields 


Priority given message 




in EBCDIC 


(decimal notation) 


PRIORITY 


5 


5 


PRIORITY 


6 


5 


PRIORITY 241 


3 


5 


PRIORITY 241 , PRI 


PRI 


241 


PRIORITY ,PRI 


PRI3 


243 


PRIORITY ,PRI 


PRO 


Priority of isassigned 
( the macro is not executed) 



Figure 23. Example of Using the PRIORITY Macro Instruction 



Designing the Message Handler 289 



REDIRECT 



The REDIRECT macro 

• queues a message for an additional destination; 

• is optional in an inmessage or outmessage subgroup of an MH; 

• may be specified more than once within a subgroup. 

REDIRECT queues a message for a destination in addition to the destinations 
specified by the FORWARD macro, when errors specified by the mask operand 
are detected. The bits specified by the error mask operand are compared with the 
setting of the bits in the message error record for the message. If specified bits in 
the message error record are on, the REDIRECT macro is executed; otherwise, 
the REDIRECT macro is not executed. 

The REDIRECT macro may not be used for redirecting messages being transmit- 
ted in initiate mode (see the INITIATE macro), or for redirecting error messages 
(see the ERRORMSG macro). 

The additional destination specified may be any single, group, process, or cascade 
list entry in the terminal table. A distribution list cannot be specified as the 
additional destination. 

REDIRECT may be used to route unsent messages to an application program, to 
return them to the originating station, or to send them to the alternate destination 
when the intended destination is inoperative. 



If REDIRECT is specified, it must appear in an inmessage or outmessage sub- 
group of an MH. 



Name 


Operation 


Operands 


[symbol] 


REDIRECT 


[mask][,CONNECT=/AND\ ] 
lOR / 

[,DEST=(destname]] 
<J opfield > 
\ ORIGIN ) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X* ' is used, leading zeros must be coded. If XL5' ' is 



i 



290 OS/MFT and OS/MVT TCAM Programmer's Guide 



connect=(and) 
loR / 



used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 

Notes: Omitting the operand or an all-zero mask causes unconditional execution. 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



DEST=( destname 
' opfield 
* ORIGIN 



Function: Specifies the additional destination. 

Default: DEST=ORIGIN 

Format: destname, opfield, or ORIGIN, destname may be up to eight bytes in 

length and is the name of any single, group, or cascade Hst entry in the terminal 

table. It must be specified within framing C \ CLn* ', X' ' or XLn' ' characters. 

opfield is the unframed name of an option field defined by an OPTION macro, 

and cannot be named ORIGIN. 

Notes: If an invalid destination is specified, REDIRECT does not execute. 

opfield refers to an option field up to eight bytes, containing the name of the 
destination. The additional destination is the station 

• specified in the option field assigned to the originating station or application 
program, if 1) REDIRECT is used in an inmessage subgroup and 2) if the 
originating station is not a switched station that called the computer to enter 
the message but did not identify itself by means of a unique ID sequence or by 
a vaUd origin field checked by an ORIGIN macro; 

• specified in the option field assigned to this line by a TERMINAL macro coded 
for a line if the originating station is a switched station that called the computer 
to enter this message, but did not uniquely identify itself; 

• specified in the option field assigned to the destination station or appUcation 
program if REDIRECT is used in an outmessage subgroup. 

ORIGIN specifies that the message in error is to be sent to the station from which 
it originated (in addition to the destinations specified in the message header). 

If this operand is omitted or if DEST= ORIGIN is specified, and the originating 
station is a switched station that has called the computer to enter the message, the 
station must identify itself by a unique ID sequence or by a vaUd origin field as 
checked by an ORIGIN macro. Otherwise TCAM is unable to identify the station 
of origin and cannot route the message to it. 



Designing the Message Handler 29 1 



RETRY 



The RETRY macro 

• tries again to initiate contact with a switched station; 

• is optional in the inmessage subgroup. 



Name 


Operation 


Operand 


[symbol] 


RETRY 


INTVL=: integer 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



INTVL»integer 



Function: Specifies the number of seconds following which the computer is to try 

again to initiate contact with a switched station. 

Default: None. Specification required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 



If the RETRY macro is specified, the RETRY= operand of the TERMINAL 
macro also must be specified. The TERMINAL macro also must specify the 
DIALNO= operand and either the CLOCK= or the CINTVL= operand. 

For more information, see the RETRY= operand of the TERMINAL macro. 



( 



292 OS/MFT and OS/MVT TCAM Programmer s Guide 



I 



SCREEN 



The SCREEN macro 

• modifies the Write operation for terminals with display screens; 

• is optional in outheader subgroups of Message Handlers for terminals with 
display screens. 

SCREEN may be used in an outheader subgroup of an MH to specify the type of 
modification to be made to the Write operation for the 2260, the 2265, or 3270. 
(See 3270 Information Display System in Appendix G for information on the 
SCREEN macro, special for the 3270.) If the user specifies the Write Display 
Control (WDC) operation, write operations begin at the position of the display 
cursor. Alternatively, the user may specify the Write Erase (WRE) function so 
that the screen is erased before the next segment is displayed, and writing begins 
at the top of the screen. Or, the user may specify the Une on which he wishes to 
write, using the Write at Line Address (WLA) function. 

If the WLA function is used, the user must specify the line address character 
desired as the first character of the header of the message to be written. If 
line-control is left in the message, the line-address character should follow any 
initial line-control characters. The user may insert the line address in the message 
header either by: 

• including the necessary assembler language instructions in an MH or in an 
application program. 

• using the MSGEDIT macro. 

The table below gives the appropriate line addresses in EBCDIC for 2260 termi- 
nals. The following MSGEDIT macro, executed in an outheader subgroup on the 
first segment of a message, would place the line address for Une number ten in the 
first byte of the header (assuming that the header contains no Une control): 

LINEADDR MSGEDIT ( ( I , XL1 ' F9 ' , ) ) 

The type of operation (WRE, WLA, WDC, XRE, XL A, XDC) to be performed 
for a display terminal is specified initially by the user in the TERMINAL macro 
for that terminal. (See the description of the ADDR= operand of the 
TERMINAL macros.) When the TERMINAL macro is executed, TCAM sets a 
byte in the terminal table entry to indicate the type of Write operation to be 
performed for aU messages directed to this terminal. The SCREEN macro 
changes the type of operation to be performed by modifying this byte (for exam- 
ple, from WLA to WRE). However, for remote operations, the change specified 
by SCREEN does not take effect until the next message is sent to the terminal; if 
WLA was changed by SCREEN to WDC, aU messages sent to the terminal after 
the current message would have a WDC operation performed for them, but the 
current message (that is, the message being processed when SCREEN executes) 
would have a WLA operation performed for it. For local operations, the change 
specified by SCREEN takes effect for the current operation. See device depend- 
ent considerations for 2260 and MH return codes. 

When WLA is changed to another Write operation by SCREEN, the user must 
still place the line address in the header of the current message, since a WLA 
operation will be performed for this message. If the operation- type operand of 
SCREEN is omitted, when SCREEN finishes executing, a return code is placed in 
register 15 to indicate what the setting of the terminal table byte was before 



Designing the Message Handler 293 



SCREEN changed it. User code may test the return code; if the code indicates 
that a WLA operation was being performed, a MSGEDIT macro may be executed 
to insert the Hne address. Otherwise, the user code may branch around the 
MSGEDIT macro (see the example following the macro description). 



Line Address Characters for the IBM 2260 Terminal 



Hexadecimal representation 


Selected line 


of EBCDIC line address 




FO 


1 


Fl 


2 


F2 


3 


F3 


4 


F4 


5 


F5 


6 


F6 


7 


F7 


8 


F8 


9 


F9 


10 


FA 


11 


FB 


12 



SCREEN has the following format: 



Name 



[symbol] 



Operation 



SCREEN 



Operands 



WRE 

iwLAi 

'WDC' 

\XRE 

fxLA 

,XDC 



[,conchars[,BLANK= ( YES 
NO 
char 



] ] 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 




Function: Specifies the type of write operation for the IBM 2265 (Remote) or the 

IBM 2260 (Local or Remote). 

Default: None. Specification optional. 

Format: WRE, WLA, WDC, XRE, XLA, or XDC. 

Notes: WRE specifies a Write Erase operation, the erasure of the screen before the 

next segment is displayed. 



( 



294 OS/MFT and OS/MVT TCAM Programmer's Guide 



conchars 



WLA specifies a Write at Line Address operation. The user must insert a line 
address character as the first character (following any initial Une-control charac- 
ters, if line control was left in the message) of the message to be written out. 

WDC specifies a Write Display Control operation. 

XRE specifies Write Erase with keyboard lock. 

XLA specifies Write at Line Address with keyboard lock. 

XDC specifies Write Display Control with keyboard lock. The keyboard lock 
feature causes the keyboard to be locked after the write. It can be used to force 
the terminal operator to look at the screen; perhaps for the purpose of reading and 
correcting a previously entered message that contained a syntax error. XLA, 
XRE, and XDC can only be used if the 2260 or 2265 device is equipped with the 
keyboard lock feature. 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn* ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn' ' characters. 

Notes: If this operand is omitted, the SCREEN function is performed uncondi- 
tionally. If the next field in the header does not match this operand, the function 
is not performed. 

A SCREEN macro specifying no WRE, WLA, or WDC operation may be issued 
to check the type of write operation in effect for the message being processed 
without changing the operation type. See the example below. 

If WLA is changed to another Write operation, the user code in the outheader 
subgroup needs to know whether to cause a line-address character to be inserted 
in the current message. The following codes may be returned by SCREEN in 
register 15: 



Code 


Operation 


X'AO' 


WDC 


X'BO' 


WLA 


X'EO' 


WRE 



BLANK= 



char 
NO 
YES 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 



Designing the Message Handler 295 



unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 

specified, it must be framed with X' ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. (, 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Example: 

The following code (in Figure 24) might be issued in an outheader subgroup to ^ 

determine whether the Write at Line Address (WLA) operation is specified in the H 

appropriate byte in the terminal table entry for the destination station for the 
message being processed, and to cause a line address of 10 to be placed in the first 
byte of the message header of the current message if WLA is specified in the 
terminal table entry. SCREEN is executed only for type A messages (as deter- 
mined by a field in the message header and the conchars operand of SCREEN). 



OUTHDR 








SCREEN 




/A 




LA 




5,X'B0' 




CLR 




5,15 




BNE 




CONTINUE 




MSGEDIT 




( (I,XL1 'F9' 


,0)) 


CONTINUE EQU 




* 




next 








instruct 


ion 







Figure 24. Example of Inserting Line Address 



i 



296 OS/MFT and OS/MVT TCAM Programmer's Guide 



SEQUENCE 



The SEQUENCE macro 

• checks the input sequence number of an incoming message; 

• inserts the output sequence number in an outgoing message; 

• is optional in inheader and outheader subgroups on non-audio lines (and may 
not be used in any other subgroup); 

• should be specified only once in each subgroup. 

If specified in an inheader subgroup, SEQUENCE scans the input sequence 
number field in the header of each message. If the sequence number is not one 
greater than the sequence number of the last message received from the same 
station or appHcation program, an error flag is set in bit 3 or 4 of the message 
error record assigned to the message (depending on whether the number is high or 
low, respectively), and a return code indicating an error is set in register 15. 

The header field for the input sequence number may contain up to four characters 
of sequence (leading zeros may be omitted from the input sequence number 
entered at the station). This field should contain a decimal representation of the 
input sequence number, and should be delimited by a blank. For example, if the 
sequence number is twelve, the field should consist of a character 1 followed by a 
character 2 followed by a delimiting blank. At the time SEQUENCE looks at the 
field, the characters should have been translated into EBCDIC by a CODE macro. 
The user should reserve five bytes in his header (by the RESERVE= operand of 
the Une group DCB macro) for insertion of the output sequence number, if used. 

TCAM maintains internal counters in the terminal table entry to keep track of the 
incoming and outgoing sequence numbers for each station and application pro- 
gram. If the SEQUENCE macro is issued in an inheader subgroup, the first 
message from a station or application program must contain the same input 
sequence number as the input counter for that station or application program. 
TCAM initially sets each input counter to 1 . The next incoming message after 
9999 must be 1. Processing continues after the maximum number is reached. 

In general, SEQUENCE in an inheader subgroup causes the input counter to be 
incremented for each message having a correct input sequence number in the 
header. If, however, a CANCELMG macro causes a message to be canceled, or if 
a STARTMH macro causes retransmission of a message header segment, the input 
sequence number is not incremented. In the latter case, the number is increment- 
ed only when the segment is successfully retransmitted. 

If specified in an outheader subgroup, SEQUENCE places an output sequence 
number in the header of each outgoing message handled by the MH. The five- 
byte output sequence number (a blank followed by four EBCDIC characters) is 
inserted immediately following the byte to which the scan pointer is pointing when 
SEQUENCE executes. When the first message is sent to a station or application 
program, a 1 is placed in the output counter for that station or application pro- 
gram; as each succeeding output message is handled, this sequence number is 
incremented by 1 and the resulting number is inserted in the header. (A count is 
maintained for each station and for each terminal group where group addressing is 
used.) A message in error being routed using a REDIRECT macro retains the 
output sequence number placed in it. 



Designing the Message Handler 297 



symbol 



Use of SEQUENCE is optional. If used, it must appear within an inheader or 
outheader subgroup. Its position must correspond to the relative position, within 
the header, of the sequence-number field. 

TCAM increments the input sequence number counter in the terminal table entry 
only if a SEQUENCE macro is issued in the inheader subgroup. TCAM incre- 
ments the output sequence number counter in the terminal table entry automati- 
cally, each time that a message is sent to the station or appUcation program. 

If SEQUENCE is included in an inheader subgroup handling header segments 
entered by a switched station that calls the computer to enter the segments, and if 
the station does not have a unique ID sequence assigned to it, SEQUENCE should 
not be executed until after an ORIGIN macro has been executed. In this case, 
ORIGIN is needed to identify the calling station so that SEQUENCE can gain 
access to the correct input counter. 



Name 


Operation 


Operands 


[symbol] 


SEQUENCE 


(no operands) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands. Five spaces must be reserved for insertion of an output 
sequence number; space is reserved by a RESERVE = operand of the line group 
DCB macro. If insufficient space is reserved, a SEQUENCE macro coded in an 
outheader subgroup is not executed, and a return code of X'04' is set in register 
15. For incoming messages, if the input sequence number in the message header 
is low, the return code is X*04', and if the number is high or if there is no valid 
decimal number in the header field being examined, the return code is X'08'. If 
the source of an incoming message is not known at the time SEQUENCE is 
reached in an inheader subgroup, the macro does not execute and a return code of 
X'OC is placed in register 15. In none of these cases is the input sequence 
counter in the appropriate terminal table entry incremented. 

Continuity of sequence numbers is maintained by the continuation and warm 
restart capabilities of the TCAM restart facihty. 



I 



298 OS/MFT and OS/MVT TCAM Programmer's Guide 



SETEOF 



The SETEOF macro 

• sets a bit in the buffer prefix to indicate an EOF message; 

• is optional in the outheader subgroup of the MH assigned to an application 
program(and should be coded in no other). 

The SETEOF macro is used to identify the last message in a data file being 
processed by an application program. When the application program receives a 
message flagged by SETEOF, the next GET or READ/CHECK it issues after the 
complete message has been received will cause control to be passed to the routine 
whose address is specified by the EODAD= operand of the application program 
input DCB for the destination queue associated with the GET or READ. Thus, 
by issuing a SETEOF macro, the user causes the application program to stop 
obtaining work units from one or more destination queues and to do whatever is 
specified by the routine located at the EODAD address. 

The SETEOF macro is issued in the outheader subgroup of the outgoing group of 
the MH handling messages routed to an application program. 

In the case of multiple-buffer headers, SETEOF must be executed for the first 
header buffer to be effective. 

SETEOF has the following format: 



Name 


Operation 


Operands 


[symbol] 


SETEOF 


[conchars[,BLANK=(YES) ]] 
Vchar; 



symbol 



conchars 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn' ' characters. 

Notes: If this operand is omitted, the SETEOF function is performed uncondition- 
ally. If the next field in the header does not match this operand, the function is 
not performed. 



Designing the Message Handler 299 



BLANK= ( YES 
' char 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES and an eight-byte field in the header is being checked 
by this macro, a blank appearing in the fifth byte of the field will be ignored and 
the sixth through ninth bytes will be considered to be the last four bytes of the 
field (assuming that no blanks are coded in the sixth through ninth bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

chars specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char and char is not the EBCDIC blank 
character, the EBCDIC blank is not ignored by this macro when it is encountered 
in the header string, but is compared to the character in the corresponding space 
in the conchars string, Hke any other character. 



{ 



300 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



END€HAR=Uhars ) 
(opfield) 



SETEOM 



The SETEOM macro 

• allows dynamic control of the amount of data required for a logical message; 

• specifies the action to be taken with the data in a buffer following the end of 
the message; 

• allows removal of delimiting characters (end-of -message indicators); 

• is permitted only in the inblock subgroup of an MH; 

• may be coded only once in the subgroup. 

The SETEOM macro allows the user to dynamically control the amount of data in 
any message either by specifying the length or by specifying an end-of -message 
(EOM) indicator. This macro causes data in an incoming transmission sequence 
to be either blocked or deblocked. If an EOM indicator is found in a buffer, then 
two messages may be formed; that is, incoming data is deblocked to form one or 
more messages. If an EOM indicator is not found, the transmission being handled 
is processed by the incoming MH, and subsequent transmissions are processed in 
the same way until an EOM indicator is detected; that is*, multiple buffers are 
blocked to form a single message. See Handling Logical Messages in this 
chapter for a more complete description of how to use the SETEOM macro. 



Name 


Operation 


Operand 


[symbol] 


SETEOM 


[ENDCHAR= (chars )][,EOM=El'B] 

\opfielcl| 
[,LENGTH=^integer ) ,opfield2)] 

iopfieldl/ 
[,PROCESS=|YES)][,REMOVE= /YES) ] 

INO / iNO / 



Function: Name of the macro. 

Default: None. Specification optional 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that delimits the message. 
Default: None. This operand must be specified if the LENGTH= operand is not 
specified. If the LENGTH= operand is specified, this operand is optional. 
Format: chars may be from one to eight nonblank characters specified in charac- 
ter or hexadecimal format. If character format is specified, the field must be 
framed with C ' or CLn* ' characters. If hexadecimal format is specified, the field 
must be framed with X* ' or XLn* ' characters, n must be the length of the 
characters. 

opfield is the name of a field defined by an OPTION macro containing the charac- 
ter or character string used as an EOM indicator. The first byte of the option field 
contains the length of the delimiter, followed by the delimiter. 



Designing the Message Handler 30 1 



Notes: If both the LENGTH= and the ENDCHAR= operands are specified, the 
message delimiter is either the length or the characters, whichever is encountered 
first. The ENDCHAR= operand cannot be coded if EOM=ETB is coded. One of 
the following return codes is passed in register 15 after this macro executes: 



Code 



Meaning 



X*00000004' An EOM indicator delimited this message. 

X'00000008' The user-specified length delimited this 

message. 
X'OOOOOOOC An EOM indicator and the user-specified 

length delimited this message. 



X'OOOOOOIO' 



No available buffer units. 



X'00000014' Buffer not processed because no option field 

was found. 



LENGTH=(Uiiteger hopfieldl) 
lopfieldU 



Function: Specifies the number of bytes in the message. 

Default: None. Must be specified if the ENDCHAR= operand is not specified. 

If the ENDCHAR= operand is specified, this operand is optional. 

Format: integer or opfieldl followed by opfield2 . integer is a decimal integer 

that may be up to 65535. opfieldl is the name of a half word defined by an 

OPTION macro, containing the length, in bytes, of the message, opfieldl is a 

halfword option field initially set to zero and used to maintain a count of the 

number of bytes already received. 

Maximum: 65535 or a hexadecimal halfword field. 

Notes: If both the LENGTH= and the ENDCHAR= operands are specified, the 

message delimiter is either the length or the characters, whichever is encountered 

first. The LENGTH= operand cannot be coded if EOM=ETB is coded. One of 

the following codes is returned in register 15 after this macro executes: 



5 



Code 



Meaning 



X*00000004' An EOM indicator delimited this message. 

X'00000008' The user-specified length delimited this 

message. 
X*OOOOOOOC' An EOM indicator and the user-specified 

length delimited this message. 



X'OOOOOOIO' 



No available buffer units. 



X'00000014' Buffer not processed because no option field 

was found. 



PROCESS= ( YES J 



Function: Specifies whether any data following an EOM indicator is to be processed 

or discarded. 

Default: PROCESS=NO 

Format: YES or NO. YES indicates that the second portion of the data is to be 

processed. NO indicates that the second portion is to be discarded; that is, the 

original message is truncated. 

Notes: When YES is specified, processing of the second portion (which is the first 



302 OS/MFT and OS/MVT TCAM Programmer's Guide 



REMOVE= JYES^ 

Uos 



E01Vf=ETB 



buffer of a new message) begins at the SETEOM macro. When the EOM indica- 
tor is encountered, a new buffer is obtained. The remaining portion of the buffer 
is moved into the new buffer that becomes a header buffer for the new message 
with the scan pointer set to the beginning of the buffer. Thus, this buffer will be 
the next buffer to be processed by this MH. The reserve space specified by the 
DCB macro is reserved in this new header buffer when it is initiaUzed. All subse- 
quent buffers of the new message also begin processing at the SETEOM macro. If 
sufficient buffer units are not available to move the remaining portion of the 
current buffer, a return code of X'lO' is set in register 15. 

NO should be used when any remaining portion of the incoming data is to be 
discarded. This means that not only the remaining portion of the current buffer is 
dropped, but all the subsequent buffers, if any, of the current message are re- 
turned to the buffer pool. 



Function: Removes EOM characters from buffers containing logical messages (or 
partial logical messages). 
Default: NO 
Format: YES or NO. 

Notes: YES causes EOM characters to be removed from incoming buffers con- 
taining parts of one or more logical messages. 

NO causes EOM characters to remain in the buffer in which they appear. NO 
must be specified if EOM=ETB is coded. 



Function: Specifies that a logical message is deUmited by an ETB (ETX, EOB) 

condition. 

Default: None. Specification optional. 

Format: EOM=ETB 

Notes: Must be coded for 2790 support. ENDCHAR= and LENGTH= operands 

cannot be coded if this operand is coded. PROCESS=YES and REMOVE=NO 

must be coded with this operand. The following code is returned in register 15 

after this macro executes: 

Code Meaning 

X'00000004' An EOM indicator delimited this message 



Designing the Message Handler 303 



SETSCAN 



The SETSCAN macro 

• explicitly moves the scan pointer forward or backward, or 

• returns in a designated register the address of the last character of a specified 
character string, or. 

e returns in register 15 the current address of the scan pointer; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroups); 

• may be specified more than once in the same subgroup. 

The SETSCAN macro explicitly repositions the scan pointer forward or backward 
in the buffer, if specified. After the previous macro has executed, the scan pointer 
is positioned at the last character of the field acted upon by that macro. 
SETSCAN moves the scan pointer a specified number of nonblank characters, to 
a specified character, or to the last character of a specified character string, so that 
one or more fields is skipped. The scan pointer is left at its new position. 

Alternatively, the scan pointer is not moved. Instead, either a designated charac- 
ter string is located, and the address of the last character of the string is placed in 
a specified register, or the current address of the scan pointer is placed in register 
15. 

Use of SETSCAN is optional in inheader and outheader subgroups, where it may 
be used as many times as desired. 

When an outgoing message is processed by an outheader subgroup, STARTMH i 

positions the scan pointer to the last reserve character in the buffer, or, if there are N| 
no reserve characters, to the last byte of the buffer prefix, or, if there is a machine 
EOA sequence, to the last byte of the EOA. If this is not the location of the next 
header field to be processed, the user may employ SETSCAN to move the scan 
pointer to the byte immediately preceding the next header field to be processed. 

For an inheader subgroup that handles messages from stations designated as 
operator control terminals, if LC=IN is coded in the STARTMH macro, a 
SETSCAN macro should be coded as the first functional macro of the subgroup, 
with a CODE macro being the second functional macro (CODE tests for operator 
commands). The SETSCAN macro should move the scan pointer past the Une 
control characters (not including the EOA), leaving it pointing to the byte imme- 
diately preceding the first byte of meaningful header data. 



i 



304 OS/MFT and OS/MVT TCAM Programmer's Guide 



SETSCAN has the following format: 



Name 


Operation 


Operands 


[symbol] 


SETSCAN 


fskipchars) 
(integer / 

[,blank=(yes) ] 

(char; 
[,POINT= f BACK ) ]. 

(forward/ 
[,move=/returnI] 

(KEEP ) 

[,RESULT=/(register)V| 
1(15) f 



symbol 



iskipchars ) 
integer ( 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the new location of the scan pointer, either a character string 
to be located or a number of characters to be advanced. 
Default: None. This operand must be specified. 

Format: skipchars or integer, skipchars can be one to eight nonblank characters 
in character or hexadecimal format. If character format is used, the string may be 
unframed or framed with C ' or CLn* ' characters. If hexadecimal format is used, 
the string must be framed with X' ' or XLn' ' characters, integer is a decimal 
integer in decimal format. 
Maximum: For integer , 65535. 

Notes: skipchars is the character or character string to which the scan pointer is to 
be moved when MOVE = KEEP is specified or whose address is to be placed in the 
register specified by RESULT* (register) when MOVE = RETURN is specified. If 
MOVE=KEEP is specified, SETSCAN operates across buffers until the string is 
found. If MOVE=RETURN is specified, the character string must be located in 
the current buffer; otherwise, SETSCAN does not execute and a return code is 
set. If register 15 is specified to contain the address of the string and the string is 
not found in the buffer, a code of X*00' is returned in the low-order byte of 
register 15. If another register is specified for the address of the string and the 
string is not found in this buffer, X'04' is returned in the last byte of register 15 
(see the description of MOVE=RETURN below). The pointer should not be 
moved to a position outside the header. If skipchars is specified, POINT = BACK 
may not be specified. 



integer is the number of nonblank characters to be skipped. If is specified in 
place of integer , TCAM returns the main-storage address to which the scan 
pointer is currently pointing. If an attempt is made to set the scan pointer outside 



Designing the Message Handler 305 



of the current buffer, SETSCAN does not execute and control passes to the next 
macro. If integer is coded, MOVE=KEEP is assumed by TCAM, even if 
MOVE = RETURN is coded in the macro (unless is coded in place of integer ). 
If is coded, the MOVE= and RESULT = operands are ignored. 



BLANK=(YES) 
NO 
(char ! 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
being counted or when encountered in the character string in the message header 
being compared to the string specified by the skipchars operand, or whether 
blanks are to be counted as characters or as part of the header string when en- 
countered in it. If EBCDIC blanks are to be counted as characters or as part of 
the header string, this operand also specifics whether some other hexadecimal 
character is to be ignored when skipping or when encountered in the header 
string. 

Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 
Notes: YES specifies that the EBCDIC blank character (X*40') is to be ignored 
by the macro whenever characters are being skipped or whenever it is encountered 
in the header character string being checked against the skip character string 
specified by the skipchars operand. For example, if BLANK= YES is coded and 
an eight-byte field in the header is being checked by this macro, a blank appearing 
in the fifth byte of the field will be ignored and the sixth through ninth bytes will 
be considered to be the last four bytes of the field (assuming that no blanks are 
coded in the sixth through ninth bytes). 



.4 



NO specifies that the EBCDIC blank character is to be treated like any other 
character when characters are being skipped or whenever it is encountered in the 
header string being compared to the string specified by skipchars . 

chars specifies that the single character replacing char is to be ignored by this 
macro whenever characters are being skipped or whenever it is encountered in the 
header string being compared to the string specified by the skipchars operand. 
That is, the macro automatically skips over the character without counting or 
performing a comparison and goes on to check the next character in the header. If 
BLANK=char is coded and char is not the EBCDIC blank character, the 
EBCDIC blank is not ignored by this macro when it is encountered in the header, 
but is counted or compared to the character in the corresponding space in the 
skipchars string, like any other character. 



POINT= (back I 

j FORWARD f 



Function: Specifies whether the scan pointer is to be moved forward or backward. 
Default: POINT=FORWARD 
Format: BACK or FORWARD. 

Notes: FORWARD specifies that the scan pointer is to be moved forward. 
BACK specifies that the scan pointer is to be moved backward. If 
POINT=BACK is specified, neither skipchars nor MOVE= RETURN may be 
specified. Also when POINT = BACK is specified, the scan pointer may not be 
moved out of the buffer in which it is located; if integer is greater than the 



{ 



306 OS/MFT and OS/MVT TCAM Programmer's Guide 



number of characters preceding the scan pointer in the buffer, the macro does not 
execute and a code of X*04' is returned in the rightmost byte of register 15. 



MOVE=( return) 
I KEEP j 



Function: Specifies whether the scan pointer is to be moved to the designated 
position and not returned to its original position before the next macro is issued, 
or is to remain stationary with the specified character string being located and the 
main-storage address of the last character in the string being returned in a desig- 
nated register. 
Default: MOVE=KEEP 
Format: RETURN or KEEP. 

Notes: If integer is replaced by zero, this operand is ignored. If integer is speci- 
fied, MOVE=KEEP is assumed by TCAM even if the macro is coded 
MOVErcRETURN. 



RESULT= /(register)) 

t(L5) / 



MOVE=RETURN may not be specified if POINT=BACK is specified. 

KEEP specifies that the scan pointer is to be moved to the designated character (if 
skipchars is coded) or moved the designated number of characters (if integer is 
coded); the pointer remains in its new location until the next macro affecting the 
scan pointer is issued. 

RETURN specifies that the scan pointer is not to be moved. Instead, the speci- 
fied character string is located and the main-storage address of the last character 
in the string is returned in the register designated by the RESULT= operand. 



Function: Specifies the general register into which the main-storage address of the 

last character of the designated character string is to be placed once the string is 

located. 

Default: RESULT=(15) 

Format: A general register 2 through 11, or 15, enclosed in parentheses. 

Notes: If the desired character string is found, the address of its last character is 

placed in the register. If RESULT=(15) is coded and the character string is not 

found in this buffer (if skipchars is coded) or if the integer specified would take 

the scan pointer out of this buffer (if integer is specified), the macro does not 

execute and a code of X'OO' is returned in the rightmost byte of register 15. 

If some register other than 15 is specified and the character string is not found in 
the buffer, or the integer specified would take the scan pointer out of the buffer, 
the macro does not execute and X*04' is returned in the low-order byte of register 
15; in this case the contents of the specified register are unchanged. 

If integer is replaced by zero, this operand is ignored. 



Designing the Message Handler 307 



Example 1: 

A SETSCAN macro that causes the scan pointer to skip forward over 5 characters 
and remain in its new position: 

SETSCAN 5 , POINT=FORWARD , MOVE=KEEP 

Example 2: 

A SETSCAN macro that results in no movement by the scan pointer, but causes 
the address of the character '=' (located to the right of the pointer) to be placed 
in register 2: 

SETSCAN C' = ' ,POINT=FORWARD,MOVE=RETURN,RESULT=( 2 ) 



( 



308 OS/MFT and OS/MVT TCAM Programmer's Guide 



SLOWPOLL 



symbol 



mask 



The SLOWPOLL macro 



• delays further polling when a line error occurs; 

• is optional in an inmessage subgroup of an MH, and 

• is not permitted in any other subgroup; 

• is not permitted in an appUcation program MH; 

• may be used more than once in an inmessage subgroup; 

• may not be used for switched lines. 

SLOWPOLL suspends further polling on a given line when errors specified by the 
error mask occur. The bits specified by the error mask operand are compared to 
the setting of the bits in the message error record for this message. If specified 
bits in the message error record are on, the polling will be suspended. Specifying 
an all-zero mask or omitting the mask operand will cause unconditional execution 
of the SLOWPOLL macro. Polling will resume after the length of time specified 
in the SECONDS = operand. 

SLOWPOLL has the following format: 



Name 


Operation 


Operands 


[symbol] 


SLOWPOLL 


[mask][,CONNECT=fAND|[,SECONDS=( integer)] 
toR / \60 / 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ter must be used. If X* ' is used, leading zeros must be coded. If XL5' ' is used, 
leading zeros may be omitted. 

Maximum: 16777215 or a five-byte, hexadecimal field. 

Note: Omitting this operand or specifying an all-zero mask causes unconditional 
execution. 



connect=(and) 



I 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: CONNECT=AND or CONNECT=OR. 

Notes: AND specifies that the macro is to be executed only if all the bits specified 

in the mask operand are on in the message error record. OR specifies that macro 

is to be executed if any bit specified in the mask operand is on in the message 

error record. 



Designing the Message Handler 309 



SECONDS=rinteger\ 

Function: Specifies the length of time, expressed in seconds, during which poUing 

on the line will be suspended. 

Default: SECONDS=60 

Format: Decimal integer. 

Minimum: 1 

Maximum: 65535 



.1 



< 



3 1 OS/MFT and OS/MVT TCAM Programmer's Guide 



TERRSET 



The TERRSET macro 

• enables the user to set a bit in the message error record; 

• is often issued before a related ERRORMSG macro, 

• is optional in inblock, inheader, inbuffer, outheader and outbuffer subgroups. 

The TERRSET macro enables the user to set on bit 20 of the message error 
record for this message. This may be used to indicate any condition for which the 
user wishes to issue an error message. A subsequent ERRORMSG macro may be 
issued specifying a mask including the user error bit. 



Name 


Operation 


Operands 


[symbol] 


TERRSET 


(no operands) 



symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands. 



Designing the Message Handler 311 



i 



symbol 



conchar 



ROUTINE^name 



TYPETABL 



The TYPETABL macro 

• builds a branch table that can be referred to by the MSGTYPE macro. 

A given message-type table named in a MSGTYPE macro is built from one or 
more TYPETABL macros. Each TYPETABL macro expands into a message-type 
character followed by the address to be branched to for that message type. The 
first TYPETABL macro of a message-type table should have the name of that 
table in the name field. The remaining TYPETABL macros for that table should 
have blank name fields and follow directly behind the TYPETABL macro having 
the table name. Within a group of TYPETABL macros, each one with a name will 
be the beginning of a new table. 



TYPETABLE has the following format: 



Name 


Operation 


Operands 


[symbol] 


TYPETABL 


conchar , ROUTINE = name 



Function: Names the macro and the message-type table. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: The single message-type comparison character. 

Default: None. Specification required. 

Format: One nonblank character in character or hexadecimal format. If character 

format is used, the character must be a single unframed character or framed with 

C* ' or CLn' \ If hexadecimal format is used, the character must be framed with 

X* ' or XLn' '. 



Function: Names a user label in the same inheader or outheader subgroup in 

which the MSGTYPE macro names the message- type table. This is the label to be 

branched to on an equal comparison. 

Default: None. Specification required. 

Format: Must conform to the rules for assembler language symbols. 



Designing the Message Handler 313 



UNLOCK 



The UNLOCK macro 

• removes a station from extended lock mode; 

• is optional in an inheader, inmessage, outheader, or outmessage subgroup. 

When a LOCK macro is used to lock a station in extended lock mode to an 
application program, the UNLOCK macro may be included in the MH to remove 
the station from extended lock mode. When coded in an inheader or outheader 
subgroup, the conchars operand may be used in conjunction with control charac- 
ters in the message header to provide the capabiUty of optional execution of 
UNLOCK. When coded in an inmessage or outmessage subgroup, the mask 
operand may be used to provide optional execution. 

The UNLOCK macro is meaningful only in the inheader subgroup of an MH 
handhng inquiry or response messages being exchanged by an appUcation program 
and a station locked to it by a LOCK macro having EXTEND coded as an oper- 
and. When the lock condition is not in effect, the macro is ignored. 

When the UNLOCK macro is issued in a inheader subgroup handling inquiry 
messages being received from a station in extended lock mode, the message 
currently being handled is routed to the destination specified in its header or by a 
FORWARD macro (and checked by a FORWARD macro) if UNLOCK is issued 
before the FORWARD macro is issued. If UNLOCK is issued after FORWARD, 
the message is routed to the application program to which the originating station 
was locked. 

The UNLOCK macro may be issued immediately following an unconditional 
LOCK macro to remove a certain message type from lock mode before the 
message is queued. For example, 

LOCK EXTEND 
UNLOCK A 

would place the station in extended lock mode for all except type A messages. 
Again, 

LOCK MESSAGE 
UNLOCK J 

would terminate message lock mode only for type J messages. 

When the UNLOCK macro is issued in an outmessage subgroup, an optional 
facility may be specified. This is the disable facility. When specified, it causes a 
switched connection to be disabled (disconnected) when the unlock is performed. 
If the locked station is on a nonswitched Une, the disable function has no effect. 

For a discussion of the lock mode and its function in a TCAM system, see the 
description of the LOCK macro. 

UNLOCK has the following format when coded in a header subgroup: 



i 



3 1 4 OS/M FT and OS/MVT TCAM Programmer's Guide 



symbol 



Name 


Operation 


Operands 


[symbol] 


UNLOCK 


[conchars[,BLANK= 


(yes) ]] 

l^char; 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



conchars 



BLANK 



=( YES ) 

NO 

(char ) 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used the string must be framed with X' ' or 
XLn* ' characters. 

Notes: If this operand is omitted, the UNLOCK function is performed uncondi- 
tionally. If the next field in the header does not match this operand, the function 
is not performed. 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as 
part of the header string, this operand also specifies whether some other hexa- 
decimal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may 
be unframed or framed with C ' or CLl ' ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLl' ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCIDC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight -byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being 
compared to the string specified by conchars. 



Designing the Message Handler 315 



char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically 
skips over the character without performing a comparison and goes on to 
check the next character in the header. If BLANK=char is coded and char 
is not the EBCDIC blank character, the EBCDIC blank is not ignored by 
this macro when it is encountered in the header string, but is compared 
to the character in the corresponding space in the conchars string, like any 
other character. 

UNLOCK specified in an inheader or inmessage subgroup removes the lock 
condition for the source terminal. In an outheader or outmessage subgroup 
the lock for the destination is removed. 

UNLOCK has the following format when coded in an inmessage or out- 
message subgroup: 



Name 


Operation 


Operand 


[symbol] 


UNLOCK 


[mask][,CONNECT=f OR ) 1[,DISABLE=/N0\] 
(and/ iVESJ 



symbol 



mask 



CONNECT=iOR ) 

Jand) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Function: Specifies the five-byte, bit configuration used to test the 
message error record for the message (see message error record in 
Appendix B), 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, 
framing characters must be specified. If X' ' is used, leading zeros 
must be coded. If XL5' ' is used, leading zeros may be omitted. 
Maximum: 16777215 or a five-byte, hexadecimal field. 
Note: Omitting the operand, or an all-zero mask, causes uncondi- 
tional execution. 

Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: CONNECT=OR or CONNECT=AND 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by the mask are on in the message error record. OR specifies that the 

macro is to be executed if any bit specified by mask is on the message error 

record. 



DISABLE=jNO { 
<YESJ 



Function: Specifies whether or not a switched line is to be disabled. 

Defauh: NO 

Format: DISABLE=NO or DISABLE=YES 

Notes: NO specifies that the Une is not to be disabled. YES specifies that the line 

is to be disabled (disconnected). 



( 



3 1 6 OS/MFT and OS/MVT TC AM Programmer's Guide 



Putting the MCP Together 



This chapter describes what the physical parts of the MCP are, how to arrange 
these parts in relation to each other, and how to assemble, link-edit, and execute a 
TCAM MCP. In addition, several sample MCPs are presented and explained. 

Arranging the Sections of the MCP 

An MCP has five sections: the activation and deactivation section (the INTRO, 
OPEN, READY, and CLOSE macros and some user code to determine whether 
INTRO executed satisfactorily); a data set definition section (the DCB macros 
defining the TCAM data sets and, if appUcation programs are to be run in con- 
junction with the MCP, one PCB macro for each application program); a terminal 
and line control area section (those macros associated with the invitation lists and 
the terminal table); a Message Handler section (one or more Message Handlers); 
and an optional user routine section (closed, user subroutines called by an MH, as 
well as exit routines referred to by the INTRO macro, by DCB macros, and by the 
STARTMH macro). These sections may be coded in the order just given, or in 
any other order, except that the activation and deactivation section must come 
first. Each MCP section and locations for coding directions are given below. The 
sample program in this chapter conforms to this organization. 

The PCB macro defining an application program must be included in the MCP. 
This macro is logically similar to a DCB macro and may be included in the data set 
definition section, or it may appear in any other section, except between OPTION 
macros, among macros defining the terminal table, or within an MH. 

The INVLIST macros defining invitation hsts must follow the macros defining the 
terminal table. 



Activation and Deactivation 



Data Set Definition 



Terminal and Line Control Area 



Message Handler 



Initializes, activates, and deactivates the MCP; 

Opens and closes the MCP data sets; 

Described in the chapter ylc//varmg and Deactivating the MCP. 



Defines the data sets for the TCAM line groups, message queues, and check- 
point and logging facilities; 
Described in the chapter Defining the MCP Data Sets . 



Defines the terminal table for the MCP; 

Defines the option fields associated with the terminal table entries; 

Defines the invitation Ust for each line; 

Described in the chapter Defining Terminal and Line Control Areas . 



Determines the way in which each incoming and outgoing message is to be 

processed; 

Routes each message to its proper destination, if possible; 

Informs the user of errors occurring during message transmission, routing, and 

handling; 

Described in the chapter Designing the Message Handler . 



Putting the MCP Together 3 1 7 



User Routine 



• Consists of closed, user subroutines that may be entered from an MH, or by an 
exit specified by an INTRO, STARTMH, FORWARD, ERRORMSG, or DCB 
macro; 

• Described in the section Including a Closed Subroutine of the chapter 
Designing the Message Handler. 

The description of each macro operand specifying an exit tells what TCAM passes 
to the routine associated with that exit, and what TCAM expects the exit routine 
to return. 



Assembling, Link Editing, and Executing the Message Control Program 

The assembly, link editing, and execution of a TCAM MCP is similar to the same 
steps in any other problem program running under OS. Sample job control 
statements are given in this section for these three steps; these statements are 
guidelines only. 



Assembling an MCP 



A typical control-card sequence for assembling a TCAM MCP is: 



Link Editing an MCP 



//ASSEMBLY 


JOB 


MSGLEVEL=1 


//STEP1 


EXEC 


ASMFC 


//ASM.SYSIN 


DD 


* 



MCP Source Deck 



A typical control-card sequence for Unk-editing an MCP is: 



//LINKEDIT 
//STEP1 

// 

//SYSPRINT 

//SYSUT1 

//SYSLMOD 

//SYSLIB 

//SYSLIN 



JOB 

EXEC 

DD 
DD 
DD 
DD 
DD 



MSGLEVEL=1 

PGM=IEWL,PARM='XREF, LIST, LET' , 

REGION=96K 

SYSOUT=A 

UNIT=SYSDA,SPACE=( 1024, ( 200,20 ) ) 

DSNAME=SYS1 . TCAMLIB,DISP=OLD 

DSNAME=SYS1 . TELCMLIB, DISP=OLD 



4 
% 



MCP Object Module 

NAME TCAMPROG(R) 

In this case, the MCP load module is to be placed in a private library called 
SYSl.TCAMLIB that has previously been created by the user. 

The SYSLIB DD statement names SYSl.TELCMLIB, a special library area 
defined at system generation time. TCAM's resident modules are located in 
SYSl.TELCMLIB. 

The MCP load module resulting from the link-edit may be stored in 
SYSLLINKLIB, or in a private library such as SYSl.TCAMLIB in the example. 



Executing an MCP 



The TCAM MCP is usually executed as the highest-priority task in the highest- 
priority partition or region in the system. The TCAM MCP is executed either by 
placing the appropriate job control statements in the card reader and using an OS 
Reader/Interpreter to place the job in the system, or by issuing from the console a 
START command referring to a cataloged procedure that contains the necessary 



i 



3 1 8 OS/MFT and OS/MVT TCAM Programmer's Guide 



//EXECMCP 


JOB 


//GOSTEP 


EXEC 


//STEPLIB 


DD 


//DD1050 


DD 


// 


DD 


// 


DD 


//DD2740 


DD 


// 


DD 


// 


DD 


//DISKDD 


DD 


//SYSABEND 


DD 



job control statements. (Starting by a START command is discussed below.) The 
job control statements needed for the execute step are similar for both cases. 

A typical control card sequence for executing an MCP is as follows (in this case, 
the MCP has two Une group data sets containing three Hnes each and a message 
queues data set residing on disk; no checkpoint or logging facihty is included). 
The load-module form of the MCP is placed on SYSl.TCAMLIB by the linkage 
editor. 

EXECUTE MCP' ,MSGLEVEL=1 

PGM=TCAMPROG , REGION^ 1 OOK 

DSNAME=SYS1 . TCAMLIB, DISP=SHR 

UNIT=025 

UNIT=026 

UNIT=027 

UNIT=015 

UNIT=016 

UNIT=017 

DSNAME=DISKDS , DISP=OLD 

SYSOUT=A 

The DISKDD DD statement is for a message queues data set residing on disk; 
DISKDD is the name specified in the DDNAME= operand of the DCB macro for 
this data set, while DISKDS is the name of the data set as specified by the 
DSNAME= operand of the lEDQDATA DD statement for the lEDQXA utihty 
used to Preformat disk message queues data sets residing on disk. 

Information on the DD statements for line group data sets and message queues 
data sets is found in the chapter Defining the MCP Data Sets . 

The STEPLIB DD statement defines SYSl.TCAMLIB, the private library on 
which the MCP was placed by the linkage editor. If the Hnkage editor had placed 
the MCP in SYSLLINKLIB, no such DD statement would be needed. As an 
alternate to the STEPLIB DD statement, a JOBLIB DD statement could define 
the private library. The JOBLIB statement would immediately follow the JOB 
statement, and would be coded as follows: 

//JOBLIB DD DSNAME=SYS1 . TCAMLIB, DISP=SHR 

Defining the private library by a STEPLIB DD statement is necessary if the MCP 
is running under MVT and is to be started by a START command. A JOBLIB DD 
statement may not be included in a cataloged procedure in SYSLPROCLIB, 
while a STEPLIB DD statement may be so included in an MVT system (see the 
next section). 

Starting the MCP by a Cataloged Procedure: The user may catalog his job control 
statements for the execute step by using the lEBUPDTE utiUty program to place 
the statements in SYSLPROCLIB. (lEBUPDTE is described in the OS publica- 
tion, Utilities .) In order to start or restart his MCP, the user need only issue a 
START command from the system console naming his cataloged procedure. (Use 
of the START command for this purpose is described in the OS publication. 
Operator's Guide.) 

In the following example, three procedures are cataloged. The first of these, 
named PROCl, causes an MCP, named MCPl and located in SYSLLINKLIB, to 
k be started. The second and third procedures, named PROC2 and PROC3, both 

cause another MCP, named MCP2 and located in a private library named 



Putting the MCP Together 3 1 9 



^ 



SYSl.TCAMLIB, to be started. The difference between PROC2 and PROC3 is 
in the line configurations specified; PROC2 contains DD statements for one Une 
group data set, while PROC3 contains DD statements for two line group data sets. 
In the initialization section of MCP2 the user has coded OPEN macros for both 
data sets, and has also coded DCB macros for both data sets. When PROC2 is 
used to start MCP2, the OPEN macros for the extra Une group data set and the 
DCB macro for this data set do not execute since no DD statement is present for 
this data set; but control passes to the next instruction in each case, and the MCP 
will be started. Thus, by specifying his cataloged procedures the user can choose 
between MCPs, or between different line configurations for the same MCP, at 
start-up time. 



To get MCP2 with two line groups, at start-up time the user would enter 

STARTPR0C3.ID 

at the system console (ID is the identification sequence that must be specified by 
TCAM Modify commands entered at the system console; see the section 
Specifying Operator Commands in Using TCAM Service Facilities). 



//STARTPGM 


JOB 


MSGLEVEL=1 






// 


EXEC 


PGM=IEBUPDTE 






//SYSPRINT 


DD 


SYSOUT=A 






//SYSUTl 


DD 


DSNAME=SYS1 .PROCLIB, 


,DISP= 


=OLD 


//SYSUT2 


DD 


DSNAME=SYS1 .PROCLIB, 


.DISP= 


=OLD 


//SYSIN 


DD 


DATA 






./ 


ADD 


NAME=PR0C1 ,LIST=ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP 1 






//DD1050 


DD 


UNIT=015 






// 


DD 


UNITED 16 






// 


DD 


UNIT=017 






//SYSABEND 


DD 


SYSOUT-A 






./ 


ADD 


NAME=PR0C2 , LIST=ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP2 






//STEPLIB 


DD 


DSNAME=SYS1 .TCAMLIB, 


,DISP= 


=SHR 


//DD2770 


DD 


UNIT=021 






// 


DD 


UNIT=022 






// 


DD 


UNIT=023 






//SYSABEND 


DD 


SYSOUT=A 






./ 


ADD 


NAME=PR0C3 , LIST^ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP2 






//STEPLIB 


DD 


DSNAME=SYS1 .TCAMLIB, 


,DISP= 


=SHR 


//DD1050 


DD 


UNIT=015 






// 


DD 


UNIT=016 






// 


DD 


UNIT=017 






//DD2770 


DD 


UNIT=021 






// 


DD 


UNIT=022 






// 


DD 


UNIT=023 






//SYSABEND 


DD 


SYSOUT=A 






./ 


ENDUP 









Sample MCPs 



This section presents three sample Message Control Programs (MCPs) together 
with associated application programs and JCL statements. The examples consisi 
of an MCP to switch messages between terminal types, an MCP with an applica 



320 OS/MFT and OS/MVT TCAM Programmer's Guide 



tion program to demonstrate inquiry and response, and an MCP with two applica- 
tion programs showing both file updating with checkpoint coordination and 
\ message retrieval. 

The programs are designed to run under MVT on a 512K IBM System/360 Model 
50. The LKED procedure used in the programs for inquiry/response and file 
updating has been modified to Unk-edit modules to a private library named 
SYSl.TCAMLIB rather than to SYSl.LINKLIB, the standard linkage library. 

The first two programs run in a single region; the third needs three regions. 
Terminal requirements are included in the explanation preceding each MCP. The 
application programs provided are guideUnes only and therefore do not demon- 
strate real processing. 

Message Switching Between Terminal Types 

Figure 25 presents an MCP designed to switch messages between IBM 1050 Data 
Communication Systems. This MCP assumes two nonswitched 1050s on a 
multipoint line and a switched 1050 on another line. The addressing and invita- 
tion characters used in the TERMINAL and INVLIST macros, and the unit 
addresses on the DD JCL statements are installation-dependent. The values 
specified in this sample program are to be used as guideUnes only. 

The MCP is written to run in two steps. The first step is an assembly creating an 
object deck. If the assembly is successful, the second step is a **link edit and go" 
using the object deck obtained from the assembly. 

In addition to message switching, this sample program permits use of the operator 
\ control facility. Operator commands may be entered either from the system 

r console or from the 1050 terminal named NYCl. 

The format of a message entered in the system depends on whether it is a message 
to be switched or an operator command. If it is an operator command it must 
begin with the four characters OPID. If it is a message to be switched, its format 
is: 

leading data X destination = data EOT 

Since the translation table is 1050, the destination name and the X must be 
entered in uppercase. The message must end with an EOT character. Examples 
of messages entered and responses received are: 

a. Entered at NYC2, a message to be switched 

X CHGO = message data newline EOT 
When CHGO calls in, it receives the response 
X CHGO = 0001 message data newline BOT 

b. Entered at NYCl, an operator command 

OPID D TP,PRITERM newline EOT 
Received at NYC 1 , the response 
IED041I PRIMARY=SYSCON 

Since all of the required INTRO operands are not specified in the assembly, the 
WTOR message 

IED002A SPECIFY TCAM PARAMETERS 



Putting the MCP Together 3 2 1 



will be received when the GO step is executed. A minimum response is S=C,U. 
Any other INTRO operands with short keyword equivalents may be altered at this 
time. Any operands not specified in the assembly but required for this execution 
(for instance, fewer cross-reference entries, a system interval, or removal of 
on-line test) may also be specified as part of the response to the WTOR. 

Each section of the sample program is commented to provide an explanation of 
the macros used and the operands specified. 



i 



322 OS/MFT and OS/MVT TCAM Programmer's Guide 



//ASMMSGSW JOB MSGLEVEL=1 

// EXEC ASMFC , PARM . ASM= ' NOLOAD , DECK ' 

//ASM.SYSIN DD * 

MSGSWTCH CSECT 

PRINT NOGEN 



** ACTIVATION AND DEACTIVATION SECTION 
* 

THIS SECTION INITIALIZES THIS MESSAGE CONTROL PROGRAM (INTRO MACRO), 
OPENS THE MCP DATA SETS ( OPEN MACROS ) , ACTIVATES THE MCP ( READY 
MACRO ) , CLOSES THE MCP DATA SETS ( CLOSE MACROS ) AND DEACTIVATES THE 
PROGRAM (RETURN MACRO). SIXTY BUFFER UNITS ( LNUNITS + MSUNITS ) ARE 
DEFINED, AND THE LENGTH OF EACH BUFFER UNIT IS SET AT 11 6 BYTES 
(KEYLEN). THE NUMBER OF UNITS PER BUFFER IS DEFINED IN THE DCB MACROS 

* IN THE DATA SET DEFINITION SECTION. THE TYPE OF STARTUP ON INTRO HAS 

* BEEN OMITTED FROM THE MACRO TO PERMIT ALTERNATE SPECIFICATION AND 
ADDITION OF OPERANDS AT EXECUTION. TWO LINE GROUPS (CONSISTING 
OF ONE LINE EACH) AND A MESSAGE QUEUES DATA SET ON REUSABLE DISK 
ARE OPENED. 



* 
* 

TCAMINIT INTRO CPB=2 , 

DISK=YES, 



CHANNEL PROGRAM BLOCKS 
DISK QUEUING UTILIZED 

PROGID=MESSAGE/SWITCHING, PROGRAM IDENTIFICATION 

LNUNITS=40, 

MSUNITS=20, 

KEYLEN=1 16, 

CR0SSRF=2, 

TRACE=10, 

DTRACE=100, 

C0NTR0L=0PID 



15,15 
OPENDISK 



ABEND 12 3, DUMP 



(DISK,( INOUT) ) 

DISK+48,DCB0FLGS 

NOEXEC 



LTR 
BZ 

NOEXEC 
* 

OPENDISK OPEN 

TM 

BNO 
* 

OPENLINE OPEN 

TM 

BNO 
* 

TM 
BNO 
* 

ALLSWELL READY 

FINISHUP CLOSE ( GROUPONE , , GROUPTWO ) 

CLOSE DISK 

L 13,4(13) 

RETURN (14,12) 



* 

* 

UNITS ASSIGNED TO LINES * 
UNITS ASSIGNED TO MAIN STORAGE* 
SIZE OF BUFFER UNITS * 

CROSS REFERENCE— DEBUG AID * 
I/O TRACE--DEBUG AID * 

SUBTASK TRACE--DEBUG AID * 
ID SEQUENCE FOR OPERATOR 
COMMANDS 

TEST IF INTRO EXECUTED 
PROPERLY 



IF NOT, ABNORMAL EXIT 

OPEN DISK QUEUE BEFORE LINES 
OPEN SUCCESSFUL 
NO - ABEND 



( GROUPONE , ( INOUT ) , GROUPTWO , ( INOUT ) ) OPEN LINE GROUPS 

GROUPONE+48 , DCBOFLGS 

NOEXEC 



GROUPTWO+48 , DCBOFLGS 
NOEXEC 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO ^- ABEND 

BEGIN PROCESSING 

CLOSE LINE GROUPS BEFORE DISK 

CLOSE DISK DATA SET 

RETURN CONTROL TO OS 

SUPERVISOR 



Figure 25. Sample Message-Switching Program (Part 1 of 5) 



Putting the MCP Together 323 



** DATA SET DEFINITION SECTION 
* 

THIS SECTION DEFINES THE DATA SETS FOR THE TCAM LINE GROUPS AND THE 
MESSAGE QUEUES ON DISK. THE DISK MESSAGE QUEUES DATA SET IS DEFINED 
TO BE REUSABLE. BOTH LINE GROUPS ARE IBM 1050 DATA COMMUNICATION 
SYSTEM GROUPS. DYNAMIC BUFFER ALLOCATION IS NOT SPECIFIED FOR 
EITHER GROUP. THEY BOTH USE THE SAME MESSAGE HANDLER ( MH ) . BUFFERS 
ARE BUILT WITH SINGLE BUFFER UNITS (BUFSIZE=116, AS IS KEYLEN ON 
THE INTRO MACRO). 



He 

* 
* 
* 

DISK 



DCB 



GROUPONE DCB 



GROUPTWO DCB 



DSORG=TQ, 
MACRF=(G,P), 
OPTCD=R, 
DDNAME=DISKDD 

DSORG=TX, 

MACRF=(G,P), 

CPRI=E, 

DDNAME=DDONE , 

TRANS=1050, 

SCT=1050, 

MH=SWITCHMH, 

INVLIST=(LISTONE), 

PCI=(N,N), 

BUFSIZE=1 16, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=(21 ,0,0,0) 

DSORG=TX, 

MACRF=(G,P), 

CPRI=S, 

TRANS=1050, 

SCT=1050, 

DDNAME=DDGRPTWO , 

jyiH=SWITCHMH, 

INVLIST=(LISTTWO), 

PCI = (N,N), 

BUFSIZE=116, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=( 21,0,0,0) 



ORGANIZATION IS TCAM DISK * 
REQUIRED OPERAND * 

DATA SET ON REUSABLE DISK * 
NAME OF ASSOCIATED DD JCL 
STATEMENT 

ORGANIZATION IS TCAM LINE 
REQUIRED OPERAND 
SEND/RECEIVE PRIORITY EQUAL 
NAME OF DD JCL STATEMENT 
1050 TRANSLATION TABLE 
SPECIAL CHARACTER TABLE 
MESSAGE HANDLER FOR LINE 
INVITATION LIST FOR LINE 
NO DYNAMIC ALLOCATION 
SIZE OF A BUFFER 
INITIAL ASSIGNMENT FOR INPUT 
INITIAL ASSIGNMENT FOR OUTPUT * 
MAXIMUM BUFFERS PER LINE * 
RESERVED FOR INSERTION OF 
DATA IN MESSAGES 

DCB FOR SECOND LINE GROUP * 

* 

SEND HAS PRIORITY OVER RECEIVE* 

He 

« 

He 
He 
He 
He 
* 
He 
He 



Figure 25. Sample Message-Switching Program (Part 2 of 5) 



I 



324 OS/MFT and OS/MVT TCAM Programmer's Guide 



** TERMINAL AND LINE CONTROL AREA 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP , THE ENTRIES 

* IN THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. THE 

* TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE LINE GROUP DEFINED 

* BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE IN THE GROUPTWO 
LINE GROUP. QUEUING IS BY TERMINAL FOR EACH TERMINAL, AND USES 
MAIN-STORAGE QUEUING WITH REUSABLE DISK BACKUP. NYCl IS DEFINED 
AS A SECONDARY OPERATOR CONTROL TERMINAL: THUS NYC1 AND THE SYSTEM 
CONSOLE ARE THE ONLY TERMINALS CAPABLE OF ENTERING OPERATOR 
COMMANDS. SINCE PRIMARY= WAS NOT SPECIFIED ON THE INTRO MACRO, 
THE SYSTEM CONSOLE IS THE PRIMARY OPERATOR CONTROL TERMINAL 
FOR THIS MCP. 



* 
* 

* 
* 



NYC1 



NYC2 



CHGO 



TTABLE LAST=CHGO 
TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN= 1 , 
TERM=1050, 
QUEUES=MR, 
ADDR=6402, 
ALTDEST=NYC2 , 
SECTERM=YES 
TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 , 

TERM=1050, 

QUEUES=MR, 

ADDR=6202, 

ALTDEST=NYC1 , 

SECTERM=NO 

TERMINAL QBY=T, 

DCB=GROUPTWO, 

RLN=1 , 

TERM=1050, 

QUEUES=MR, 

ADDR=6202, 

DIALNO=NONE 



THE LAST ENTRY IN THE TABLE 

QUEUING BY TERMINAL * 

ASSOCIATED DCB * 

RELATIVE LINE NUMBER * 

TYPE OF TERMINAL * 

MAIN STORAGE, REUSABLE DISK * 

ADDRESSING CHARACTERS * 

ALTERNATE DESTINATION * 
SECONDARY OPERATOR CONTROL 

SECOND TERMINAL IN GROUP * 

* 

* 

NOT AN OPERATOR CONTROL 

TERMINAL 

TERMINAL FOR GROUPTWO * 

* 
* 
* 
* 

MAY NOT BE CALLED BY THE 
CENTRAL PROCESSING UNIT 
BOTH ENTRIES ARE ACTIVE 



LISTONE 
LISTTWO 



UTERM=YES 
INVLIST ORDER=(NYC1+640B,NYC2+620B) GROUPONE INVITATION LIST 
INVLIST ORDER=(CHGO+620B) GROUPTWO INVITATION LIST 



Figure 25. Sample Message-Switching Program (Part 3 of 5) 



Putting the MCP Together 325 



* 

** MESSAGE HANDLER SECTION 
* 

THIS SECTION PROVIDES THE MESSAGE-SWITCHING CAPABILITY OF THE MCP . 
INCOMING MESSAGES ARE TRANSLATED TO EBCDIC AND CHECKED TO SEE IF 
THEY ARE OPERATOR COMMANDS. IF SO THEY ARE PROCESSED BY THE OPERATOR 
CONTROL FUNCTION. IF THEY ARE NOT, THE 'DATE AND TIME IS INSERTED IN 
THE MESSAGE (USING 16 OF THE 21 BYTES RESERVED BY THE "RESERVE^" 
OPERAND IN THE DCB ) AND THE MESSAGE IS FORWARDED TO THE DESTINATION 
SPECIFIED IN THE HEADER. OUTGOING MESSAGES ARE SEQUENCED (USING THE 
REMAINING RESERVED CHARACTERS), TRANSLATED BACK TO 1050 LINE CODE 
AND SENT. 



* 

* 
* 
* 

He 

* 
* 

sic 4( H( )K H( 

SWITCHMH STARTMH LC=OUT 
* 

* INCOMING GROUP OF THE MH 
* 

INGROUP INHDR 

CODE , 
SETSCAN 



X 
FORWARD ( 4 ) 



INEND 



REMOVE LINE CONTROL 



PROCESS HEADERS ONLY 

TRANSLATE TO EBCDIC 

SET SCAN POINTER TO AN X 

FORWARD TO THE DESTINATION 

NAMED IN THE NEXT FOUR BYTES 

OF THE MESSAGE 

END OF THE INCOMING GROUP 



* OUTGOING GROUP OF THE MH 



OUTGROUP OUTHDR 

SETSCAN - 
SEQUENCE 
CODE , 
OUTEND 



PROCESS HEADERS ONLY 
SET SCAN POINTER TO AN = 
INSERT SEQUENCE NUMBER 
TRANSLATE TO 1050 LINE CODE 
END OF THE OUTGOING GROUP 



,1 



DCBOFLGS 



EQU 
END 



X' 10' 



Figure 25. Sample Message-Switching Program (Part 4 of 5) 



( 



326 i OS/MFT and OS/MVT TCAM Programmer's Guide 



//LKGMSGSW JOB MSGLEVEL=1 ,REGI0N=1 20K,TYPRUN=HOLD 
//S2 EXEC LKEDG 

//LKED.SYSLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
//LKED.SYSIN DD * 

OBJECT DECK HERE 



//GO.STEPLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
//GO.DISKDD DD DSNAME=SAMP1 ,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
//SYSABEND DD SYSOUT=A 
//GO.DDONE DD UNIT=015 
//GO.DDGRPTWO DD UNIT=011 



Figure 25. Sample Message-Switching Program (Part 5 of 5) 



Putting the MCP Together 327 



Inquiry and Response \ 

Figure 26 presents an MCP designed to use the conversational capabilities of 
TCAM. This MCP locks a terminal to an application program from the time a 
message is entered until a response is provided. A sample application program is 
also provided, but its functions are limited to recognition of messages. It does not 
do any processing. 

The MCP assumes two nonsvi^itched IBM 1050 Data Communication Systems on 
a multipoint line, and a single switched 1050 on another line. The addressing and 
invitation characters used in the TERMINAL and INVLIST macros, and the unit 
addresses on the DD JCL statements are installation-dependent. The values 
specified in the sample programs are guidelines only. 

The programs are written to run in three steps. The MCP and the application 
program are first assembled and object decks are obtained. If there are no 
assembly errors, the object decks are link-edited. The final step is the execution 
of the MCP, which will attach the application program after the MCP data sets are 
open. 

The inquiry and response feature has a limiting effect on transmission in the 
multipoint line group. If one of the terminals on the line enters a message, the 
other is locked out (cannot enter data) until the response has been received by the 
originating terminal. The terminal on the other line may enter messages during a 
lock on the multipoint Une. The message format for the example is: 

origin b sequence fe = b data b /( 1 6 b )EOT ^ 

If the origin and sequence fields are valid, the response is: ^ 

origin b date b time b sequence b = out-sequence b data b/ 

MESSAGE RECEIVED EOT 
If the origin field was incorrectly specified, the response is: 

ORIGIN FIELD WRONG 

If the sequence number was incorrectly specified, the response is: 

origin bdatebtimeb sequence SEQUENCE NUMBER HIGH 

or 

origin bdatebtimeb sequence SEQUENCE NUMBER LOW 

Since the translation table used is 1050, the origin field must be entered in upper- 
case characters. 

The MCP includes the operator control facility. Operator commands may be 
entered from the system console or from the terminal named NYCl. If an opera- 
tor command is entered at NYCl, it must begin with the four-character identifier 
OPID. 

Since all of the required INTRO operands are not specified in the assembly of the 
MCP, a WTOR message 



IED002A SPECIFY TCAM PARAMETERS 



will be received at the system console when the GO step is executed. The mini- 
mum required response is 'S=C,U'. Any other INTRO operands with short 



( 



328 OS/MFT and OS/MVT TCAM Programmer's Guide 



keyword equivalents may be altered, and operands not specified in the assembly 
but required for this execution may also be specified as part of the response to the 
WTOR. 

Each section of the sample MCP and the application program that follows it has 
been commented to provide explanation of the macros used and the operands 
specified. 



Putting the MCP Together 329 



//ASMINQ JOB MSGLEVEL=1 

// EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

//ASM.SYSIN DD * 

INQUIRY CSECT 

PRINT NOGEN 

* 

** ACTIVATION AND DEACTIVATION SECTION 
* 

THIS SECTION INITIALIZES THE MESSAGE CONTROL PROGRAM (INTRO MACRO), 
OPENS THE MCP DATA SETS (OPEN MACRO), ATTACHES THE APPLICATION 
PROGRAM (ATTACH MACRO), ACTIVATES THE MCP (READY MACRO), CLOSES THE 
MCP DATA SETS (CLOSE MACRO), AND DEACTIVATES THE PROGRAM (RETURN 
MACRO). SIXTY BUFFERS ( LNUNITS + MSUNITS ) ARE DEFINED, AND THE 
LENGTH OF EACH BUFFER UNIT SET AT 11 6 ( KEYLEN ) . THE NUMBER OF UNITS 
PER BUFFER IS DEFINED IN THE DCB MACROS IN THE DATA SET DEFINITION 
SECTION. THE TYPE OF STARTUP ON INTRO HAS BEEN OMITTED FROM THE 
MACRO TO PERMIT ALTERNATE SPECIFICATION AND ADDITION OF OPERANDS AT 
EXECUTION. TWO LINES ARE OPENED. 



* 
* 

* 

* 
* 

TCAMINIT INTRO DISK=NO, NO DISK QUEUING * 

PROGID=INQUIRY/RESPONSE, PROGRAM IDENTIFICATION * 

LNUNITS=40, BUFFERS ASSIGNED TO LINES * 

MSUNITS=20, BUFFERS ASSIGNED TO MAIN STOR * 

KEYLEN=116, SIZE OF BUFFER UNITS * 

CR0SSRF=2, CROSS-REFERENCE - DEBUG AID * 

TRACE=10, I/O TRACE - DEBUG AID * 

DTRACE=100, SUBTASK TRACE - DEBUG AID * 

CONTROL=OPID ID SEQUENCE FOR OPERATOR 

* CONTROL MESSAGES 

15,15 TEST IF INTRO EXECUTED 

OPENLINE PROPERLY 



ABEND 12 3, DUMP 



( GROUPONE , ( INOUT ) ,GROUPTWO, ( INOUT ) ) OPEN LINE GROUPS 



LTR 
BZ 

NOEXEC 

OPENLINE OPEN 

TM 

BNO 
* 

TM 
BNO 

ATTACH EP=INQAP 
READY 
FINISHUP CLOSE ( GROUPONE ,, GROUPTWO ) 
L 13,4(13) 
RETURN (14,12) 



IF NOT, ABNORMAL EXIT 



GROUPONE+48 , DCBOFLGS 
NOEXEC 

GROUPTWO+48 , DCBOFLGS 
NOEXEC 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO - ABEND 

ATTACH APPLICATION PROGRAM 
BEGIN PROCESSING 
CLOSE LINE GROUPS 
RETURN CONTROL TO OS 
SUPERVISOR 



Figure 26. Sample Inquiry/Response Program (Part 1 of 9) 



i 



330 OS/MFT and OS/MVT TCAM Programmer s Guide 



* 

* 

** DATA SET DEFINITION SECTION 

THIS SECTION DEFINES THE DATA SETS FOR THE TCAM LINE GROUPS AND THE 
PROCESS CONTROL INTERFACE. BOTH LINE GROUPS ARE IBM 1050 DATA 
COMMUNICATION SYSTEM GROUPS. DYNAMIC BUFFER ALLOCATION IS NOT 
SPECIFIED FOR EITHER GROUP. THEY BOTH USE THE SAME MESSAGE HANDLER 
(MH). BUFFERS ARE BUILT WITH SINGLE BUFFER UNITS. THE PROCESS 
CONTROL BLOCK REFERS TO A DIFFERENT MH . SINCE THE APPLICATION 
PROGRAM GETS AND PUTS MESSAGES, THE BUFFER SIZE FOR THE PROCESS 
CONTROL BLOCK IS THE SAME AS THAT FOR THE LINES. 



* 
* 
* 

GROUPONE DCB 



GROUPTWO DCB 



QPROC 



PCB 



DSORG=TX, 


ORGANIZATION IS TCAM LINE 


* 


MACRF=(G,P), 


REQUIRED OPERAND 


* 


CPRI=E, 


SEND/RECEIVE PRIORITY EQUAL 


♦ 


DDNAME=DDGRPONE , 


NAME OF DD JCL STATEMENT 


♦ 


TRANS=1050, 


1050 TRANSLATION TABLE 


♦ 


SCT=1050, 


SPECIAL CHARACTERS TABLE 


« 


MH=LINEMH, 


MESSAGE HANDLER FOR LINE 


« 


INVLIST=(LISTONE), 


INVITATION LIST FOR LINE 


* 


PCI = (N,N), 


NO DYNAMIC BUFFER ALLOCATION 


* 


BUFSIZE=116, 


SIZE OF A BUFFER 


* 


BUFIN=2, 


INITIAL ASSIGNMENT - INPUT 


♦ 


BUF0UT=4 , 


INITIAL ASSIGNMENT - OUTPUT 


« 


BUFMAX=4 , 


MAXIMUM BUFFERS PER LINE 


« 


RESERVE=(21 ,0,0,0) 


RESERVED FOR INSERTION OF 
DATA IN MESSAGES 




DSORG=TX , 


DCB FOR SECOND LINE GROUP 


« 


MACRF=(G,P), 




♦ 


CPRI=S, 


SEND HAS PRIORITY OVER RECEIVE* 


DDNAME=DDGRPTWO , 




♦ 


TRANS=1050, 




« 


SCT=1050, 




« 


MH=LINEMH , 




* 


INVLIST=(LISTTWO), 




« 


PCI = (N,N), 




« 


BUFIN=2, 




♦ 


BUF0UT=4 , 




« 


BUFMAX=4 , 




* 


RESERVE=(21 ,0,0,0) 






MH=APPMH , 


PROCESS CONTROL BLOCK 


an 


BUFSIZE=116, 




« 


BUFIN=5, 




* 


BUF0UT=5 , 




♦ 


RESERVE=(5,0) 







Figure 26. Sample Inquiry/Response Program (Part 2 of 9) 



Putting the MCP Together 33 1 



* 

** TERMINAL AND LINE CONTROL SECTION 
* 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP, THE ENTRIES IN 

* THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. THE 

* TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE LINE GROUP DEFINED 
BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE IN THE GROUPTWO 
LINE GROUP (THIS IS A SWITCHED LINE, GROUPONE IS NON-SWITCHED). 
QUEUING IS BY TERMINAL FOR EACH TERMINAL, AND USES MAIN-STORAGE ONLY 
QUEUING. NYC1 IS DEFINED AS A SECONDARY OPERATOR CONTROL TERMINAL. 
TWO PROCESS ENTRIES ARE ALSO DEFINED, ONE FOR GET PROCESSING AND 
THE OTHER FOR PUT. QUEUING FOR THE GET PROCESSOR IS MAIN-STORAGE 
ONLY, AND IT IS DEFINED AS ITS OWN ALTERNATE DESTINATION. 
BOTH PROCESS ENTRIES REFER TO THE SAME PROCESS CONTROL BLOCK ( PCB ) . 



* 
* 
* 
* 
* 

* 
* 



GPRC 



PPRC 
NYC1 



NYC2 



* 

CHGO 



LAST ENTRY IN THE TABLE 
PCB NAME 

MAIN-STORAGE ONLY QUEUING 
ALTERNATE DESTINATION 
PUT PROCESS ENTRY 
QUEUING BY TERMINAL 
ASSOCIATED DCB 
RELATIVE LINE NUMBER 
TYPE OF TERMINAL 
MAIN-STORAGE ONLY QUEUES 
ADDRESSING CHARACTERS 
SIZE OF A BLOCK 
SECONDARY OPERATOR CONTROL 
TERMINAL 
SECOND TERMINAL IN GROUPONE 



LISTONE 
LISTTWO 



TTABLE LAST=CHGO 
TPROCESS PCB=QPROC, 

QUEUES=MO, 

ALTDEST=GPRC 
TPROCESS PCB=QPROC 
TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 , 

TERM=1050, 

QUEUES=MO, 

ADDR=6402, 

NTBLKSZ=( 116), 

SECTERM=YES 

TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN=1 

TERM=1050, 
QUEUES=MO, 
ADDR=6202, 
NTBLKSZ=( 116), 
ALTDEST=NYC1 , 
SECTERM=NO 

TERMINAL QBY=T, 

DCB=GROUPTWO, 

RLN= 1 , 

TERM=1050, 

QUEUES=MO, 

ADDR=6202, 

NTBLKSZ=( 116), 

DIALNO=NONE MAY NOT BE CALLED BY THE 

CENTRAL PROCESSOR 
INVLIST ORDER=(NYC1+640B,NYC2+620B) GROUPONE INVITATION LIST 
INVLIST ORDER=(CHGO+620B) GROUPTWO INVITATION LIST 



ALTERNATE DESTINATION 
NOT A SECONDARY OPERATOR 
CONTROL TERMINAL 
TERMINAL FOR GROUPTWO 



* 



* 
* 
* 
* 
* 
* 
* 



* 
* 

He 

* 



* 
* 
* 



Figure 26. Sample Inquiry/Response Program (Part 3 of 9) 



i 



332 OS/MFT and OS/MVT TCAM Programmer's Guide 






* 

** MESSAGE HANDLER SECTION 
* 

* THIS SECTION PROVIDES THE MESSAGE HANDLING FUNCTION OF THE MCP . 

* IT CONTAINS TWO MHS . THE FIRST RECEIVES INPUT FROM LINES AND 

* FORWARDS TO THE GET APPLICATION PROGRAM AFTER ITS ORIGIN AND 

* SEQUENCE NUMBER HAVE BEEN VERIFIED, AND THE DATE AND TIME HAVE BEEN 

* INSERTED. THE TERMINAL THAT SENT THE MESSAGE IS LOCKED TO THE 

* APPLICATION PROGRAM UNTIL A RESPONSE IS RECEIVED. MESSAGES WITH 

* INVALID ORIGIN OR SEQUENCE NUMBER ARE CANCELED, AND AN ERROR 

* MESSAGE BUILT. OUTGOING MESSAGES ARE SEQUENCED, AND AN EOB/EOT IS 

* INSERTED AT THE END OF THE MESSAGE. THE SECOND MH RECEIVES INPUT 

* FROM THE APPLICATION PROGRAM AND FORWARDS IT TO THE DESTINATION 

* PROVIDED BY THE APPLICATION PROGRAM. 

* 

* FIRST MESSAGE HANDLER - FOR LINES 
* 

LINEMH STARTMH LC=OUT, REMOVE LINE CONTROL * 

STOP=YES, STOP ON ERRORS * 

CONV=YES CONVERSE MODE REQUESTED 

INHDR TO PROCESS HEADERS 

CODE 100 CONVERT TO EBCDIC FROM 1050 

* LINE CODE 

ORIGIN 4 GET FOUR-CHARACTER ORIGIN 

* FROM MESSAGE 
DATETIME INSERT DATE AND TIME 
SEQUENCE VERIFY SEQUENCE NUMBER 
FORWARD DEST=C'GPRC' FORWARD TO GET PROCESSOR 
LOCK MESSAGE LOCK TERMINAL TO APPLICATION 

* PROGRAM UNTIL RESPONSE 
INMSG FULL MESSAGE RECEIVED 
CANCELMG X ' 5800000000 ' CANCEL MESSAGES WITH INVALID 

* ORIGINS AND SEQUENCE NUMBERS 
MSGGEN X'4000000000' , IF ORIGIN WRONG, SEND * 

CL1 8 'ORIGIN FIELD WRONG' THIS MESSAGE 
ERRORMSG X ' 1 000000000 ' , IF SEQUENCE HIGH, RETURN THIS * 

DEST=ORIGIN, MESSAGE WITH THE HEADER TO ITS* 

DATA=C • SEQUENCE NUMBER HIGH' ORIGIN 
ERRORMSG X ' 0800000000 ' , IF SEQUENCE LOW, RETURN THIS * 

DEST=ORIGIN, MESSAGE WITH THE HEADER TO ITS* 

DATA=C' SEQUENCE NUMBER LOW' ORIGIN 
INEND END OF INCOMING GROUP 

OUTHDR TO PROCESS HEADERS 

SETSCAN C'=' SET SCAN POINTER TO AN = 

SEQUENCE INSERT SEQUENCE NUMBER 

CODE , TRANSLATE BACK TO LINE CODE 

MSGFORM INSERT EOB/EOT IN MESSAGE 

OUTEND END OF OUTGOING GROUP 

* THIS MH 

* SECOND MESSAGE HANDLER - FOR APPLICATION PROGRAM 

APPMH STARTMH LC=OUT REMOVE LINE CONTROL 

INHDR TO PROCESS HEADERS 

FORWARD DEST=PUT TO DESTINATION IN HEADER 



Figure 26. Sample Inquiry/Response Program (Part 4 of 9) 



Putting the MCP Together 333 



INEND 
OUTHDR 
SETSCAN C'=' 
SETEOF C'CLOSEAP' 



OUTEND 
DCBOFLGS EQU X ' 1 ' 
END 



PROVIDED BY PUT APPLICATION 

PROGRAM 

END OF INCOMING GROUP 

PROCESS OUTGOING HEADERS 

RESET SCAN POINTER 

SET END OF FILE IF CLOSEDOWN 

MESSAGE RECEIVED 

END OF OUTGOING GROUP 



Figure 26. Sample Inquiry/Response Program (Part 5 of 9) 



i 



C 



334 OS/MFT and OS/MVT TCAM Programmer s Guide 



//ASMINQAP JOB MSGLEVEL=1 

// EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

//ASM.SYSIN DD * 

INQAP CSECT 

PRINT NOGEN 



** INITIALIZATION SECTION 



* THIS SECTION DOES THE NECESSARY INITIALIZATION FOR THE PROGRAM. 

* IT SAVES REGISTERS, ESTABLISHES ADDRESSABILITY AND SETS THE 

* NEW SAVE AREA ADDRESS IN THE STANDARD SAVE AREA REGISTER. 



t I 



SAVE (14,12 

LR 12,15 
USING INQAP, 12 

ST 13, SAVE+4 

LA 13, SAVE 

* 

** ACTIVATION SECTION 



SAVE REGISTERS 
RESET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
SAVE ADDRESS OF SAVE AREA 
NEW SAVE AREA ADDRESS 



* THIS SECTION OPENS THE DATA SETS FOR THE PROGRAM. 
* 

^ H( 4(4( sic 

OPEN 



OPEN INPUT DCB 
OPEN OUTPUT DCB 



EQU * 
OPEN DCBIN 
OPEN DCBOUT 

** PROCESSING SECTION 

* THIS SECTION CONTROLS THE ACCESS, PROCESSING, AND RETURN OF MESSAGES, 

* IT ALSO TESTS FOR THE NEED TO CLOSE DOWN THE PROGRAM, AND CLEARS 

* WORK AREAS IF NOT. 



GET END OF WORK AREA ADDRESS 

GET A MESSAGE 

SET LENGTH COUNTER 

GET START OF MSG DATA 



* 






iic*:ic4c* 






LOOP 


EQU 


* 




LA 


10,GOTMSG 




GET 


DCBIN, WORK 




LA 


9,1 




LA 


2,WORK+8 


LOOP 2 


EQU 


* 




CLI 


0(2), CV 


^ 


BE 


PUT 




LA 


9,1(9) 




LA 


2,1(2) 




CR 


2,10 


:|c 


BE 


CLOSEM 


^ 


B 


LOOP 2 


PUT 


EQU 


* 




LA 


2,1(2) 




MVC 


0( 16,2),GOTMSG 




LA 


9,27(9) 



SEARCH FOR END OF DATA 

IF FOUND, COMPLETE PROCESSING 

INCREMENT LENGTH 
BUMP TO NEXT CHARACTER 
END AND NO / 
YES - CLOSE DOWN 

CONTINUE SEARCH 



GET PAST LAST CHARACTER 
PUT 'MSG RECEIVED' IN MSG 
ADD INSERT LENGTH 



Figure 26. Sample Inquiry/Response Program (Part 6 of 9) 



Putting the MOP Together 335 



9,DCBOUT+82 
DCBOUT,WORK 
WORK,C' ' 
W0RK-f1( 149), WORK 
LOOP 



PUT LENGTH IN LRECL FIELD 
PUT THE MESSAGE 

CLEAR WORK AREA TO BLANKS 
GET ANOTHER MESSAGE 



STH 
PUT 
MVI 
MVC 
B 
* 

** DEACTIVATION SECTION 
* 

* THIS SECTION CLOSES THE DATA SETS FOR THE PROGRAM AND RETURNS TO 

* THE OS SUPERVISOR 
* 

CLOSEM 



CLOSE INPUT DCB 

CLOSE OUTPUT DCB 

RESTORE ADDRESS OF SAVE AREA 

RETURN TO OS SUPERVISOR 



EQU * 
CLOSE DCBIN 
CLOSE DCBOUT 
L 13, SAVE+4 
RETURN (14,12) 
* 

** ERROR HANDLING SECTION 
* 

* THIS SECTION PROVIDES THE ERROR HANDLING FOR UNCORRECTABLE 

* ERRORS AND END OF DATA. 



I/O 



ERROR 



EQU 
WTO 
B 



* 

' SYNAD 
CLOSEM 



ENTERED * 



UNCORRECTABLE ERROR 
CLOSE DOWN THE PROGRAM 



END 



END OF DATA INDICATOR 
CLOSE DOWN THE PROGRAM 



EQU * 

WTO 'EODAD ENTERED' 

B CLOSEM 

** DATA SET DEFINITION SECTION 

4c 

* THIS SECTION DEFINES THE DATA SETS USED BY THE PROGRAM. 

He 

DCBIN DCB 



DCBOUT 



DCB 



DSORG=PS , 

BLKSIZE=124, 

DDNAME=APPIN, 

SYNAD=ERROR, 

EODAD=END , 

LRECL=1 16, 

OPTCD=W, 

MACRF=GM 

DSORG=PS , 

BLKSIZE=124, 

DDNAME=APPOUT , 

SYNAD=ERROR, 

LRECL=1 16, 

OPTCD=WU , 

MACRF=PM 



PHYSICAL SEQUENTIAL 
SIZE OF MESSAGE AND WORK 
NAME OF DD JCL STATEMENT 
UNCORRECTABLE ERROR HANDLER 
END OF DATA HANDLER 
SIZE OF LOGICAL RECORD 
BUILD PREFIX FOR SOURCE 
DCB FOR GET 



* 
* 

4c 
* 
4c 
4c 
4c 

4c 
4c 
4c 
4c 
4e 
4c 



DCB FOR PUT 



Figure 26. Sample Inquiry/Response Program (Part 7 of 9) 



i 



336 OS/MFT and OS/MVT TCAM Programmer's Guide 



* 

** WORK AREA DEFINITION SECTION 

* THIS SECTION DEFINES THE WORK AREAS USED BY THE PROGRAM. 

Hi ^H HH HH Hfi 

SAVE DC 18F'0' PROGRAM SAVE AREA 

WORK DC 150C' ' WORK AREA FOR MESSAGE 

GOTMSG DC C MESSAGE RECEIVED' MESSAGE PROCESSED INDICATOR 
* 

END 



Figure 26. Sample Inquiry/Response Program (Part 8 of 9) 



Putting the MCP Together 337 



//LKDINQ JOB MSGLEVEL=1 

// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD ( 

//LKED. SYS IN DD * 

OBJECT DECK HERE 

NAME INQUIRY(R) 
//LKDINQAP JOB MSGLEVEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 



NAME INQAP(R) 
//GOINQ JOB MSGLEVEL=1 ,REGION=120K,TYPRUN=HOLD 
//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
// EXEC PGM=INQUIRY 
//GO . SYSABEND DD SYSOUT=A 
//APPIN DD QNAME=GPRC 
//APPOUT DD QNAME=PPRC 
//DDGRPONE DD UNIT=029 
//DDGRPTWO DD UNIT=021 



Figure 26. Sample Inquiry/Response Program (Part 9 of 9) 



( 



338 OS/MFT and OS/MVT TCAM Programmer's Guide 



File Updating with Checkpoint Coordination 

Figure 27 presents an MCP that demonstrates coordination of checkpointing by 
the MCP and an appUcation program. This MCP also can switch messages and 
use the operator control facility. Finally, a second application program utilizes the 
retrieve capabilities of the POINT macro. Two lines are assumed, one a point-to- 
point line with two IBM 1050s, and the other supporting a single nonswitched 
IBM 2740. The addressing and invitation characters used in the TERMINAL and 
INVLIST macros, and the unit addresses on the DD JCL statements are 
installation-dependent. The values specified in the sample program are guidelines 
only. 

The job is set up to run in three steps. The MCP and both application programs 
are first assembled, then object decks from the first step are link-edited. As the 
final step, the MCP is executed. The MCP will prompt at the system console 
when it is time for the appUcation programs to be started. 

The format of the message depends upon the function desired. If it is a message 
to be switched, the format on input is: 

destination bSb origin b data bEOT 
If the origin is correct, the message received at the destination is: 

destination bSb origin b data 
If the origin is invalid, the message received at the source will be: 

ORIGIN FIELD WRONG 

If it is a message for the appUcation program that does the fUe update, the input 
format is: 

destination bAb sequence b data b/(16b)EOT 
For valid sequence numbers, the message received at the destination is: 

out'Sequence b destination bAb sequence b date b time b data 
If the sequence number is invalid, the message received at the source is: 

SEQUENCE NUMBER HIGH 
or 

SEQUENCE NUMBER LOW 

Messages for the retrieve application program may be formatted either: 

destination h/h data bEOT 

or 

destination bAb sequence h/h data bEOT 

where destination is the name of the process entry, and sequence is the sequence 
number of the message. The format of data in either of the two above messages: 

type 
i 



termname 

I I I I 



sequence 
number 



J_L 



where termname is an eight-byte field that is left adjusted and padded right with 
blanks, type is either character I (for input) or character O (for output), and 
sequence number is a five-byte field containing the sequence number of the 
message to be retrieved (in character, right adjusted, and padded left with zeros). 



Putting the MCP Together 3 39 



Operator commands entered from NYCl or CHGO must begin with the identifier 
OPID. Because of the translation tables used, messages entered by NYCl and 
NYC2 must specify destination and origin in uppercase, while the same fields 
when entered by CHGO may be in either upper or lowercase. 

Since all of the required INTRO operands were not specified in the assembly, the 
WTOR message 

IED002A SPECIFY TCAM PARAMETERS 

will be received at the console when the GO step is executed. A minimum re- 
sponse must specify some sort of restart with the S= operand. Any other oper- 
ands with a short keyword equivalent specified in the assembly may be altered, 
and any operands not specified but required for this execution may also be 
specified as part of the response to the WTOR. 

The MCP and its associated application programs are commented to provide an 
explanation of the macros used and the operands specified. 



4 



i 



340 OS/MFT and OS/MVT TCAM Programmer's Guide 



//ASMUPDT JOB MSGLEVEL=1 

// EXEC ASMFC,PARM.ASM=' LOAD, DECK' 

//ASM.SYSIN DD * 

UPDTCKPT CSECT 

PRINT NOGEN 

4( 4c H( 9i( ^c 



** ACTIVATION AND DEACTIVATION SECTION 
* 

* THIS SECTION INITIALIZES THE MESSAGE CONTROL PROGRAM (INTRO MACRO! 

* OPENS THE MCP DATA SETS (OPEN MACROS), INDICATES THAT THE 

* APPLICATION PROGRAMS MAY BE STARTED (WTO MACRO), ACTIVATES THE 
MCP (READY MACRO), CLOSES THE DATA SETS (CLOSE MACROS) AND 
DEACTIVATES THE PROGRAM ( RETURN MACRO ) . SIXTY BUFFERS ( LNUNITS + 
MSUNITS) ARE DEFINED, AND THE LENGTH OF EACH BUFFER UNIT SET AT 
116 (KEYLEN). THE NUMBER OF UNITS PER BUFFER IS DEFINED IN THE 
DCB MACROS IN THE DATA SET DEFINITION SECTION. THE TYPE OF 
STARTUP ON INTRO HAS BEEN OMITTED FROM THE MACRO TO PERMIT 
ALTERNATE SPECIFICATION AND ADDITION OF OPERANDS AT EXECUTION. 
TWO LINE GROUPS ARE OPENED. 



* 
* 
* 

He 

* 
* 

* 



TCAMINIT INTRO CPB=2 , 

DISK=YES, 



CHANNEL PROGRAM BLOCKS 
DISK QUEUING USED 



* 

PROGID=CHECKPOINT/COORDINATION, PROGRAM IDENTIFICATION * 

BUFFERS ASSIGNED TO LINES * 

BUFFERS ASSIGNED TO MAIN STOR * 

SIZE OF BUFFER UNITS * 

CHECKPOINT EVERY 30 MINUTES * 

CKREQ MACROS IN F I LEAP * 

CROSS-REFERENCE - DEBUG AID * 







LNUNITS=40, 






MSUNITS=20, 






KEYLEN=116, 






CPINTVL=180D, 






CKREQS=2 , 






CR0SSRF=2, 






TRACE=10, 






DTRACE=100, 


^ 




CONTROL-OPID 




LTR 


15,15 


^ 


BZ 


OPENDISK 


NOEXEC 


ABEND 


123, DUMP 


OPENDISK 


EQU 


* 




OPEN 


(DISK,(INOUT) ) 




TM 


DISK+48,DCBOFLGS 


* 


BNO 


NOEXEC 




OPEN 


( CKPT , ( INOUT ) ) 




TM 


CKPT+48,DCBOFLGS 


^ 


BNO 


NOEXEC 




OPEN 


( GROUPONE , ( INOUT ) , GRi 




TM 


GROUPONE+48 , DCBOFLGS 


He 


BNO 


NOEXEC 




TM 


GROUPTWO+48 , DCBOFLGS 




BNO 


NOEXEC 



I/O TRACE - DEBUG AID 

SUBTASK TRACE - DEBUG AID 

ID SEQUENCE FOR OPERATOR 

COMMANDS 

TEST IF INTRO EXECUTED 

IMPROPERLY 

ABNORMAL EXIT 



OPEN DISK QUEUE FIRST 
OPEN SUCCESSFUL 
NO - ABEND 

OPEN CHECKPOINT QUEUE NEXT 
OPEN SUCCESSFUL 
NO - ABEND 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO - ABEND 



WTO 'TIME TO START APPLICATION PROGRAMS' 
READY BEGIN PROCESSING 



Figure 27, Sample Checkpoint Coordination Program (Part 1 of 1 1) 



Putting the MCP Together 34 1 



* 

* 
DISK 



CKPT 



CLOSE ( GROUPONE , , GROUPTWO ) 

CLOSE CKPT 

CLOSE DISK 

L 13,4(13) 

RETURN ( 14,12) 



DATA SET DEFINITION SECTION 



CLOSE LINE QUEUES FIRST 
CLOSE CHECKPOINT QUEUE NEXT 
CLOSE DISK QUEUE LAST 
RETURN CONTROL TO OS 
SUPERVISOR 



THIS SECTION DEFINES THE DATA SETS FOR THE TCAM DISK QUEUE, 

THE CHECKPOINT QUEUE, AND THE LINE GROUPS AND APPLICATION PROGRAM 

PROCESS CONTROL INTERFACE. ONE LINE GROUP USES TWO IBM 1050 DATA 

COMMUNICATION SYSTEMS AND THE OTHER USES THE IBM 2740 

SYSTEM. DYNAMIC BUFFER ALLOCATION IS NOT SPECIFIED FOR EITHER 

GROUP. BOTH USE THE SAME MESSAGE HANDLER ( MH ) , AND BOTH USE 

BUFFERS BUILT OF SINGLE UNITS. THE PROCESS CONTROL BLOCKS 

REFER TO A DIFFERENT MH . BUFFER SIZE FOR BOTH APPLICATION 

PROGRAMS IS THE SAME AS THAT FOR THE LINE GROUPS. 



DCB 



DCB 



GROUPONE DCB 



GROUPTWO DCB 



DSORG^TQ , 

MACRF=(G,P ), 

OPTCD=R, 

DDNAME=DISKDD 

DSORG-TQ, 

MACRF=(G,P), 

OPTCD-C, 

DDNAME=CKPTDD 

DSORG=TX, 

MACRF=(G,P), 

CPRI-E, 

DDNAME=DDONE , 

TRANS=1050, 

SCT=1050, 

MH=LINEMH, 

INVLIST=( INVONE), 

PCI-(N,N), 

BUFSIZE=1 16, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=( 21,0,0,0) 

DSORG=TX, 
MACRF=(G,P), 
CPRI=E, 
TRANS=274F, 
SCT=274F, 
DDNAME=DDTWO , 
MH=LINEMH, 
INVLIST=( INVTWO), 
PCI-(N,N), 
BUFSIZE-1 16, 
BUFIN=2, 
BUF0UT=4 , 
BUFMAX=4 , 
RESERVE=( 21,0,0,0) 



ORGANIZATION IS TCAM DISK 
REQUIRED OPERAND 
DATA SET ON REUSABLE DISK 
NAME OF DD JCL STATEMENT 
CHECKPOINT DATA SET 

DATA SET IS CHECKPOINT 

ORGANIZATION IS TCAM LINE 

SEND/RECEIVE PRIORITY EQUAL 

1050 TRANSLATION TABLE 

SPECIAL CHARACTERS TABLE 

MESSAGE HANDLER FOR LINE 

INVITATION LIST FOR LINE 

NO DYNAMIC BUFFER ALLOCATION 

SIZE OF A BUFFER 

INITIAL ASSIGNMENT - INPUT 

INITIAL ASSIGNMENT - OUTPUT 

MAXIMUM BUFFERS PER LINE 

RESERVED FOR INSERTION OF 

DATA IN MESSAGES 

DCB FOR SECOND LINE GROUP 



FOLDED 2740 TRANSLATION TABLE 



* 

* 
* 

* 
* 
* 

* 

* 



Figure 27. Sample Checkpoint Coordination Program (Part 2 of 1 1) 



i 



342 OS/MFT and OS/MVT TCAM Programmer's Guide 



QPROC PCB 



FILE PROCESS CONTROL BLOCK 



RETRV 



PCB FOR RETRIEVE 



MH=APPMH , 
BUFSIZE=1 16, 
BUFIN=5, 
BUF0UT=5 , 
RESERVE=( 5,0 ) 
PCB MH=APPMH , 

BUFSIZE=1 16, 
BUFIN=5, 
BUF0UT=5 , 
RESERVE=( 5,0) 

* 

** TERMINAL AND LINE CONTROL SECTION 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP, THE ENTRIES 

* IN THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. 

* IT ALSO DEFINES AN OPTION FIELD TO MAINTAIN A COUNTER OF MESSAGES 

* RECEIVED. THE TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE 
LINE GROUP DEFINED BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE 
IN THE GROUPTWO LINE GROUP. QUEUING IS BY TERMINAL FOR EACH 
TERMINAL, AND MAIN-STORAGE QUEUING WITH REUSABLE DISK BACKUP IS 
USED. NYC1 AND CHGO ARE BOTH DEFINED AS SECONDARY OPERATOR CONTROL 
TERMINALS. FOUR PROCESS ENTRIES ARE ALSO DEFINED, TWO FOR GET AND 

* TWO FOR PUT PROCESSING. QUEUING FOR THE GET ENTRIES IS MAIN- 

* STORAGE WITH REUSABLE DISK BACKUP. 



COUNTIN 

FILE 



PUTF 
GETR 



PUTR 
NYC1 



* 

NYC2 



CHGO 



TTABLE LAST=CHGO 

OPTION H 

TPROCESS PCB=QPROC, 
CKPTSYN=YES , 
QUEUES=MR, 
ALTDEST=FILE 

TPROCESS PCB=QPROC 

TPROCESS PCB=RETRV, 
QUEUES=MR, 
ALTDEST=GETR 

TPROCESS PCB=RETRV 

TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN=1 , 
TERM=1050, 
QUEUES=MR, 
ADDR=6402, 
NTBLKSZ=( 116), 
OPDATA=0 , 
SECTERM=YES 

TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 

TERM=1050, 

ADDR=6202, 

QUEUES=MR, 

OPDATA=0 , 

NTBLKSZ=( 116) 

TERMINAL QBY=T, 

DCB=GROUPTWO , 
RLN=1 , 
TERM=274F, 
QUEUES=MR, 
ADDR=E201 , 



LAST ENTRY IN THE TABLE 

OPTION FIELD FOR COUNTER 

PCB NAME * 

FOR CHECKPOINTING * 

MAIN-STORAGE, REUSABLE BACKUP * 

ALTERNATE DESTINATION 

SECOND PROCESS ENTRY FOR FILEAP 

PCB NAME * 



SECOND PROCESS ENTRY FOR ARRET 

QUEUING BY TERMINAL * 

ASSOCIATED DCB * 

RELATIVE LINE NUMBER * 

TYPE OF TERMINAL * 

QUEUING TYPE * 

ADDRESSING CHARACTERS * 

SIZE OF A BLOCK * 

INITIAL VALUE OF OPTION * 
SECONDARY OPERATOR CONTROL 
TERMINAL 

SECOND TERMINAL IN GROUP * 

* 

* 

* 

TERMINAL ON OTHER LINE GROUP * 

* 
* 

NONSWITCHED WITH CHECKING * 

* 
* 



Figure 27. Sample Checkpoint Coordination Program (Part 3 of 1 1) 



Putting the MCP Together 343 



NTBLKSZ=( 116), 

OPDATA=0 , 

SECTERM=YES 
INVONE INVLIST ORDER=( NYC1 +640B,NYC2+620B ) GROUPONE INVITATION LIST 
INVTWO INVLIST ORDER=( CHGO+E20 1 , CHGO+E201 ) GROUPTWO INVITATION LIST 

* POLL TWICE BEFORE DELAY 

** MESSAGE HANDLER SECTION 

* THIS SECTION PROVIDES THE MESSAGE HANDLING FUNCTION OF THE MCP . 

* IT CONTAINS TWO MHS . THE FIRST RECEIVES INPUT FROM LINES AND 

* FORWARDS TO THE DESTINATION SPECIFIED IN THE MESSAGE, WHICH MAY BE 
EITHER ANOTHER STATION OR AN APPLICATION PROGRAM. MESSAGES ARE 
COUNTED, AND THE DATA INSERTED DEPENDS UPON A MESSAGE-TYPE 
INDICATOR SPECIFIED IN THE MESSAGE. INVALID MESSAGES ARE 
CANCELED AND MESSAGES INDICATING THE ERROR ARE RETURNED TO THE 
ORIGINATING STATION. THE SECOND MESSAGE HANDLER RECEIVES INPUT 
FROM EITHER OF THE APPLICATION PROGRAMS, SEQUENCES THEM AND 
RETURNS THEM TO THE DESTINATION SPECIFIED IN THE WORK AREA BUILT BY 
THE APPLICATION PROGRAM. 



* 

* 
* 
* 
* 

* 

LINEMH 



STARTMH LC=OUT 

INHDR 

CHECKPT 

COUNTER COUNTIN 

CODE , 

FORWARD DEST=** 

MSGTYPE A 

SEQUENCE 

DATETIME 

MSGTYPE S 

ORIGIN , 

INMSG 

CANCELMG X * 5800000000 ' 



TAKE OUT LINE CONTROL 
PROCESS INCOMING HEADERS 
CHECKPOINT OPTION FIELDS 
COUNT HEADERS RECEIVED 
TRANSLATE TO EBCDIC 
FORWARD TO DESTINATION NAMED 
IN NEXT FIELD OF MESSAGE 
TO AN APPLICATION PROGRAM 
YES - SEQUENCE VERIFY IT 
INSERT DATE AND TIME 
TO A SWITCHED TERMINAL 
YES - VERIFY ORIGIN 
TO PROCESS COMPLETE MESSAGE 
CANCEL MESSAGES WITH INVALID 
ORIGIN OR SEQUENCE NUMBER 
SEND INVALID ORIGIN MESSAGE 
BACK TO WHOEVER SENT IT 
SEND SEQUENCE HIGH MESSAGE 






APPMH 



MSGEN X'4000000000' , 

CL1 8 'ORIGIN FIELD WRONG' 
MSGEN X' 1000000000' , 

CL20' SEQUENCE NUMBER HIGH' TO ITS SOURCE 
MSGEN X ' 0800000000 ' , SEND SEQUENCE LOW MESSAGE * 

CL1 9 'SEQUENCE NUMBER LOW' TO ITS SOURCE 
INEND END OF INCOMING GROUP 

OUTHDR PROCESS OUTGOING HEADERS 

MSGFORM INSERT FOB/EOT AT END 

CODE , CONVERT BACK TO LINE CODE 

OUTEND END OF OUTGOING GROUP OF 

THIS MH 
STARTMH LC=OUT REMOVE LINE CONTROL 

INHDR PROCESS INCOMING HEADERS 

FORWARD DEST=PUT FORWARD TO DESTINATION PROVIDED 

BY APPLICATION PROGRAM 
INEND END OF INCOMING GROUP 

OUTHDR PROCESS OUTGOING HEADERS 

SEQUENCE SEQUENCE OUTGOING MESSAGES 

OUTEND END OF OUTGOING GROUP 



DCBOFLGS EQU X ' 1 ' 
END 



Figure 27. Sample Checkpoint Coordination Program (Part 4 of 1 1) 



i 



344 OS/MFT and OS/MVT TCAM Programmer's Guide 



VASMAPP1 JOB MSGLEVEL=1 

V EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

VASM.SYSIN DD * 

^ILEAP CSECT 

PRINT NOGEN 

** INITIALIZATION SECTION 
* 

* THIS SECTION ESTABLISHES ADDRESSABILITY AFTER SAVING THE CALLER 

* REGISTERS. A QSTART MACRO IS THE FIRST STATEMENT IN THE PROGRAM 

* BECAUSE IT IS NEEDED IN ORDER TO USE THE CKREQ MACRO. 
* 



FOR CKREQ USAGE 
SAVE REGISTERS 
SET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
SAVE ADDRESS OF SAVE AREA 
SET NEW SAVE AREA ADDRESS 



***** 






QSTART 




SAVE (14,12),, 




LR 12,15 




USING FILEAP, 12 




ST 13,SAVE+4 




LA 13, SAVE 


***** 





** ACTIVATION SECTION 
* 

* THIS SECTION OPENS ALL APPLICABLE DATA SETS. IN THIS EXAMPLE, THE 

* ONLY DATA SETS OPENED ARE THE TCAM DCBS . IN A TRUE FILE UPDATING 

* PROGRAM, THE DATA SETS FOR THE FILES WOULD ALSO BE OPENED IN THIS 

* SECTION. 
* 

OPEN DCBIN 
OPEN DCBOUT 

In* 

F** PROCESSING SECTION 
* 

THIS SECTION DOES THE PROCESSING REQUIRED TO UPDATE FILES, AND TAKE 
THE COORDINATED OS AND TCAM CHECKPOINTS. SINCE THIS IS ONLY AN 
EXAMPLE, NO FILES ARE UPDATED. COMMENTS ARE PROVIDED TO EXPLAIN 
WHERE THE UPDATING AND CHECKPOINTING WOULD BE DONE IN A TRUE FILE 
UPDATING PROGRAM. CHECKPOINTS ARE TAKEN AFTER EVERY 5 UPDATES. 



OPEN INPUT DCB 
OPEN OUTPUT DCB 



* 
* 
* 
* 
* 
* 
***** 

LOOP 



LOOP 2 



EQU 

LA 

GET 

LA 

LA 

LA 

EQU 

CLI 

BE 



* 

2,5 

DCBIN, WORK 

5 , GOTMSG 

4,1 

3,WORK+8 

* 

0(3), C'/' 
PUT 



SET A LOOP CONTROL 
GET A TCAM MESSAGE 
GET END OF WORK AREA 
SET LCRECL COUNT 
GET WORK AREA START 

SEARCH FOR END OF DATA 
FOUND - BUILD RESPONSE 



LA 
LA 
CR 
BE 



3,1(3) 
4,1(4)^ 
3,5 
CLOSEM 



BUMP TO NEXT BYTE 
BUMP LRECL COUNTER 
END OF WORK 
YES - ERROR 



Figure 27. Sample Checkpoint Coordination Program (Part 5 of 1 1) 



Putting the MCP Together 345 





B 


LOOP 2 


PUT 


EQU 


* 




LA 


3,1(3) 




MVC 


0( 16,3 ),GOTMSG 




LA 


4,27(4) 




STH 


4,DCBOUT+82 


^ 


PUT 


DCBOUT , WORK 


^ 


BCT 


2 , LOOP 


OSCKPT 


BCR 


0,0 



CKREQ 



GO LOOK AT NEXT BYTE 

GET PAST / 

PUT RECEIVED IN MSG 

INCREMENT LRECL COUNTER 

SET LRECL FIELD 

PUT THE MESSAGE BACK TO THE 

TCAM QUEUES 

DECREMENT A^fD TEST LOOP CONTROL 

THE INSTRUCTIONS NEEDED TO OS 
CHECKPOINT THE FILE JUST 
UPDATED WOULD BE PLACED HERE 
TCAM APPLICATION PROGRAM QUEUE 
CHECKPOINT 

REPLY YES OR NO ' , REP, 1 , WECB 

CLEAR ECB FOR A WAIT 
WAIT FOR RESPONSE 

REPLY YES 

YES - CLOSE DOWN 

CLEAR REPLY AREA 

IK CLEAR WORK AREA TO BLANKS 

GET ANOTHER MESSAGE 

* 

** DEACTIVATION SECTION 
* 

* THIS SECTION DEACTIVATES THE DATA SETS USED BY THE PROGRAM. ANY 

* OTHER DATA SETS OPENED IN THE ACTIVATION SECTION WOULD BE CLOSED 

* IN THIS SECTION. 
* 

CLOSEM 



CTEST 


EQU 


* 




WTOR 


'TIME TO CLOSE 




XC 


WECB (4), WECB 


^ 


WAIT 


ECB=WECB 




CLI 


REP,C'Y' 


^ 


BE 


CLOSEM 




XC 


REP(8),REP 




MVI 


WORK, X' 40' 




MVC 


W0RK+1( 149), wo: 




B 


LOOP 



i 



EQU * 
CLOSE DCBIN 
CLOSE DCBOUT 
L 13, SAVE+4 
RETURN (14,12) 
* 

* 

** ERROR HANDLING SECTION 



CLOSE INPUT DCB 

CLOSE OUTPUT DCB 

RESTORE ADDRESS OF SAVE AREA 

RETURN TO OS SUPERVISOR 



THIS SECTION PROVIDES THE ERROR HANDLING REQUIRED FOR 



* UNCORRECTABLE ERRORS AND THE 
* 



END-OF-DATA SITUATIONS. 



***9iC)i( 






ERROR 


EQU 
WTO 
B 


* 

•SYNAD ENTERED' 
CLOSEM 


END 


EQU 
WTO 
B 


* 

'EODAD ENTERED' 
CTEST 



UNCORRECTABLE ERROR 
CLOSE DOWN THE PROGRAM 



END OF DATA INDICATOR 
TEST IF CLOSEDOWN WANTED 



Figure 27. Sample Checkpoint Coordination Program (Part 6 of 11) 



i 



346 OS/MFT and OS/MVT TCAM Programmer s Guide 



4c 

** CHECKPOINT SECTION 
* 

* THIS SECTION PROVIDES THE CHECKPOINTING AS SPECIFIED IN THE 

* EXIT LIST OPERAND OF THE DCB MACROS. 
* 

EXIT 



EQU 
BCR 



0,0 



IF OS CHECKPOINTING WERE 
NEEDED (PER THE EXLST 
OPERAND OF THE DCB MACROS ) 
THIS WOULD BE A ROUTINE TO DO 
THE CHECKPOINTING 
THIS COORDINATES WITH THE 
TCAM CHECKPOINT 



* 

* 
* 

CKREQ 
* 

** DATA SET DEFINITION SECTION 
* 

* THIS SECTION PROVIDES ONLY THE TWO TCAM DCBS . ANY OTHER DCBS 

* RELATIVE TO A FILE TO BE UPDATED WOULD BE DEFINED IN THIS SECTION. 



Hc^H^HcHc 




DCBIN DCB 


DSORG=PS, 




BLKSIZE=124, 




DDNAME=APPLIN, 




SYNAD=ERROR, 




EODAD=END, 




EXLST=EXITLIST, 




LRECL=1 16, 




OPTCD=W, 


\ 


MACRF=GM 


DCBOUT DCB 


DSORG=PS, 




BLKSIZE=124, 




DDNAME^APPLOUT , 




SYNAD^^ERROR, 




EXLST=EXITLIST, 




LRECL=1 16, 




OPTCD=WU, 




MACRF=PM 


***** 




* 




** WORK AREA 


DEFINITION SECTION 


* THIS SECTION DEFINES THE WORK AR 
* 


***** 




SAVE DC 


ISF'O' 


REP DC 


2F'0' 


WECB DC 


F'O' 


WORK DC 


150C' ' 


GOTMSG DC 


C MESSAGE RECEIVED' 


EXITLIST DC 


X'8F' 


DC 


AL3(EXIT) 



PHYSICAL SEQUENTIAL 
SIZE OF MESSAGE AND WORK 
NAME OF DD JCL STATEMENT 
UNCORRECTABLE ERROR HANDLER 
END OF DATA HANDLER 
OS CHECKPOINT EXIT LIST 
SIZE OF LOGICAL RECORD 
BUILD PREFIX FOR SOURCE 
DCB FOR GET 
OUTPUT DCB 



* 
* 
* 
* 
* 
* 
* 
* 

* 
* 
* 
* 
* 
* 
* 



DCB FOR PUT 



USED BY THE PROGRAM. 



SAVE AREA 

REPLY AREA FOR WTOR 

ECB FOR WTOR 

WORK AREA FOR MESSAGE 

MESSAGE PROCESSED INDICATOR 

EXIT FOR CHECKPOINT 

ADDRESS OF CHECKPOINT ROUTINE 



END 



Figure 27. Sample Checkpoint Coordination Program (Part 7 of 1 1) 



Putting the MCP Together 347 



//ASMAPP2 JOB MSGLEVEL=1 

// EXEC ASMFC , FARM . ASM= ' NOLOAD , DECK ' 

//ASM.SYSIN DD * 

RETRIEVE CSECT 

PRINT NOGEN 

* 

** INITIALIZATION SECTION 



* THIS SECTION PROVIDES THE NECESSARY INITIALIZATION FOR THE PROGRAM 

* INCLUDING SAVING OF REGISTERS AND ESTABLISHING ADDRESSABILITY. 

^ )3c ^ ^ ^ 



SAVE 
LR 



( 14,12),,* 

12, 15 
USING RETRIEVE, 12 
ST 
LA 



SAVE REGISTERS 
RESET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
13,SAVE+4 SAVE ADDRESS OF SAVE AREA 

13, SAVE SET NEW SAVE AREA ADDRESS 

* 

** ACTIVATION SECTION 

* THIS SECTION OPENS THE DATA SETS USED IN THE PROGRAM. 



OPEN DCB FOR INPUT 
OPEN DCB FOR OUTPUT 



OPEN DCBIN 
OPEN DCBOUT 

* 

** PROCESSING SECTION 
* 

* THIS SECTION DOES THE PROCESSING NECESSARY TO DETERMINE FROM THE 

* INPUT MESSAGE THE MESSAGE TO BE RETRIEVED, RETRIEVES IT AND SENDS 

* IT BACK TO THE REQUESTER OF THE ORIGINAL MESSAGE. 
* 

L00P1 

GET END OF WORK AREA ADDRESS 
GET REQUESTER MESSAGE 
GET START OF MESSAGE 



LOOP 2 



EQU 


* 


LA 


1 , PTWORK 


GET 


DCBIN, WORK 


LA 


2,WORK+8 


EQU 


* 


CLI 


0(2), C'/' 


BE 


PROCESS 


LA 


2,1(2) 


CR 


2,10 


BE 


CLOSEM 



START OF DATA 

YES - PICK UP RETRIEVE DATA 

BUMP TO NEXT CHARACTER 
END AND NO / 
YES - CLOSE DOWN 



B 



LOOP 2 



CHECK FOR / 



PROCESS 



EQU 

MVC 

MVC 

MVC 

PACK 

XC 

CVB 



TERMWORK( 8 ) , 1 ( 2 ) 
IOWORK( 1 ),9( 2 ) 
DOUBLE( 5 ), 10( 2 ) 
D0UBLE+6( 2 ), DOUBLE ( 5 ; 
DOUBLE (6), DOUBLE 
3 , DOUBLE 



PUT TERMNAME IN POINT WORK 
PUT I OR IN POINT WORK 
PUT SEQUENCE IN WORK AREA 
CONVERT TO PACKED DECIMAL 
CLEAR HIGH-ORDER BYTES 
CONVERT TO HEXADECIMAL 



Figure 27. Sample Checkpoint Coordination Program (Part 8 of 11) 



i 



348 OS/MFT and OS/MVT TCAM Programmer's Guide 



//LCDUPDT JOB MSGLEVEL=1 

// EXEC LKED,PARM.LKED- 'LIST, LET, XREF' 

//LKED.SYSLMOD DD DSN-SYS 1 . TCAMLIB , DISP=OLD 



r //LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME UPDTCKPT(R) 
//LKDAPP1 JOB MSGL£:VEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS 1 . TCAMLIB , DISP=OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME FILEAP(R) 
//LKDAPP2 JOB MSGLEVEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS 1 . TCAMLIB , DISP-OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME RETRIEVE! R) 

//GOUPDT JOB MSGLEVEL=1 ,TYPRUN=HOLD,REGION=120K 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC, PGM=UPDTCKPT 

//SYSABEND DD SYSOUT=A 

//DISKDD DD DSNAME=SAMP1 ,DISP=SHR 

//CKPTDD DD DSNAME=SAMP2,UNIT=231 1 , V0LUME=SER=TSTAM1 , SPACE=( TRK, ( 3 ) ), 

// DISP=(NEW,CATLG) 

I //DDONE DD UNIT=015 
' //DDTWO DD UNIT=017 

//G0APP1 JOB MSGLEVEL-1 ,TYPRUN=HOLD 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC PGM=FILEAP 

//APPLIN DD QNAME=FILE 

//APPLOUT DD QNAME-PUTF 

//G0APP2 JOB MSGLEVEL=1 ,TYPRUN=HOLD 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC PGM=RETRIEVE 

//APP2IN DD QNAME-GETR 

//APP20UT DD QNAME=PUTR 

Figure 27. Sample Checkpoint Coordination Program (Part 11 of 1 1) 



Putting the MCP Together 351 



i 



i 



.CDUPDT JOB MSGLEVEL=1 

EXEC LKED , FARM . LKED= 'LIST, LET , XREF ' 
.KED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD 
.KED.SYSIN DD * 

OBJECT DECK HERE 

^E UPDTCKPT(R) 
.KDAPP1 JOB MSGLEVEL=1 

EXEC LKED 
:jKED.SYSLMOD dd dsn=sysi .tcamlib,disp=old 

^KED.SYSIN DD * 

OBJECT DECK HERE 

\ME FILEAP(R) 

:kdapp2 job MSGLEVEL=1 

EXEC LKED 
LKED.SYSLMOD DD DSN=SYS1 . TCAMLIB,DISP=OLD 
LiKED.SYSIN DD * 

OBJECT DECK HERE 

PME RETRIEVE! R) 

30UPDT JOB MSGLEVEL=1 ,TYPRUN=HOLD,REGION=120K 

JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=UPDTCKPT 
SYSABEND DD SYSOUT=A 
DISKDD DD DSNAME=SAMP1 ,DISP=SHR 

CKPTDD DD DSNAME=SAMP2,UNIT=2311 , V0LUME=SER=TSTAM1 ,SPACE=( TRK, ( 3 ) ) , 
1^ DISP=(NEW,CATLG) 

l!)D0NE DD UNIT=015 
DDTWO DD UNIT=017 

G0APP1 JOB MSGLEVEL=1 ,TYPRUN=HOLD 
JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=FILEAP 
APPLIN DD QNAME=FILE 
APPLOUT DD QNAME=PUTF 
G0APP2 JOB MSGLEVEL=1 ,TYPRUN=HOLD 
JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=RETRIEVE 
'APP2IN DD QNAME=GETR 
'APP20UT DD QNAME=PUTR 



5ure 27. Sample Checkpoint Coordination Program (Part 11 of 1 1) 







Putting the MCF Together 35 1 



i 



( 



Writing TCAM-Compatible Application Programs 



As described previously, a TCAM message may consist of header and text por- 
tions. The header portion is the primary concern of the Message Handler (MH) 
sections of the Message Control Program (MCP). If any processing of text 
portions of messages is required, it is performed by an application program , 
written by the user to suit the needs of his particular application. The main 
concern of TCAM with respect to an application program is to pass messages to 
the program for processing and later to return the messages to the appropriate 
station. (However, there may be no return message, as in the case of a file update 
application.) TCAM provides the means of transferring data between the parti- 
tions (GET, PUT, READ, WRITE, and CHECK macros), and provides a unique 
scheme for buffer usage for application programs. AppUcation programs run 
asynchronously with the MCP, usually in another partition or region, but always 
as a separate system task or subtask. The MCP must have higher priority than 
any application program, since the MCP must have control after system interrupt 
(this becomes extremely important if the user's application program has a program 
loop that might cause continued contention with the MCP for control). 

TCAM application programs need not be concerned with the station at which a 
message originated, or with the transmission code of the Une, or with what the 
station line control had been. TCAM automatically handles Une control in the 
Message Control Program. However, if a response message is generated, the 
appUcation programmer must consider line-control characters in the response, 
unless a MSGFORM macro is coded in the outheader subgroup handling messages 
for the destination station. The response message must be in line code unless the 
CODE macro is inserted in the outgoing group handUng messages for the destina- 
tion station. 

Messages to be processed are placed in a destination queue by a Message Handler; 
a destination queue and its process entry in the terminal table are defined by a 
TPROCESS macro. A message from a station (or from an application program) 
can be routed to any predefined application program by a FORWARD macro. 

The GET or READ macros that obtain messages from the destination queues 
transfer the data to a user-specified work area. (The work area and the units of 
work placed in it are discussed below.) Once in the work area, the data is ana- 
lyzed and processed by the application program. Optionally, a PUT or a WRITE 
macro causes a response message to be returned to the Message Control Program 
for transmission either to a station (not necessarily the one that originated the 
message), to a list of destinations, or to another application program. 

TCAM application programs allow the user to define at execution time, by the 
QNAME= parameter on the DD card, which of the destination queues specified 
in the terminal table is to be linked to the related data set. 

TCAM allows the user to run his appUcation programs in a non-teleprocessing 
environment for debugging, and then run them under TCAM without reassem- 
bling. The user may include such MCP-related, appUcation-program TCAM 
macros as TCOPY, ICOPY, QCOPY, TCHNG, ICHNG, MRELEASE, and 
MCPCLOSE (aU of which are discussed below) in an application program being 
debugged in a non-teleprocessing environment, provided that the macro definition 
library for the system under which the program is assembled includes the neces- 



Writing TCAM-Compatible Application Programs 353 



sary macro definitions (as the result of a system generation procedure). When 
these macros are encountered at execution time in a system having no MCP, a 
return code is generated and control passes to the next instruction; otherwise, 
execution of the program is not hindered. 

In some applications, the required processing may be such that one destination 
queue can handle all the messages, and a single apphcation program having a 
single interface with the MCP can perform the processing. If various kinds of 
processing are required, there are two means of providing it: 

• Each of several application programs may be provided with its own interface 
with the MCP, and the destination field in the message header used to route the 
message to the appropriate destination queue for the desired program. 

• Alternatively, all messages that require processing are routed to the same 
application program, where a user-written analysis routine determines the kind 
of message received, based upon a user-specified code-in the message. The 
messages are transferred by this routine to the appropriate processing routines, 
or possibly to a processing program in another partition or region (by a PUT or 
WRITE back to the MCP). 

When the destination field in the header is used to route messages to the appropri- 
ate processing program, the processing needed for the message must be deter- 
mined with Message Handler faciUties. Messages requiring different processing 
can be handled by MSGTYPE or PATH macros (see the descriptions of these 
macros). 

Application programs transfer data to and from the MCP using GET/PUT 
(QSAM) or READ/WRITE/CHECK (BSAM) macro instructions. Support is 
provided for fixed-, variable-, and undefined-format work units. When using 
TCAM's GET/PUT support, the user may specify move or locate mode, but not 
substitute mode. 

If the EODAD= operand is specified in the input DCB macro, the SETEOF 
macro may be issued in the MCP to indicate the end of a file of data, and the 
EODAD exit is taken on the next GET or READ after TCAM moves end-of- 
message into the user's work area. On succeeding GETs or READs, normal 
processing continues. If EODAD is not specified at end-bf-data, the apphcation 
program may stop issuing GETs or READs and issue a CLOSE macro to close the 
input DCB. If no SETEOF macro is issued, the GET or READ with CHECK is 
not finished until a message arrives on the queue. Time of entry to EODAD is 
controlled by the user because of the real-time nature of the process queue for the 
application program. The SYNAD exit for logical errors is handled in the same 
manner as under BSAM and QSAM. The SYNAD AF and SYNADRLS macros 
may be used. 

Certain other features can also be incorporated into an apphcation program: 

• A PUT or WRITE work area prefix can be used to specify the destination to 
which a message can be sent. 

• A GET or READ work area prefix can be used to receive the name of the 
message source. 

• The work area contents may be described to TCAM for PUT or WRITE 
operations and by TCAM for GET or READ operations as first segment, 
intermediate segment, last segment, or single-segment message. 

These three options may be included at execution time by a DD card parameter 
(DCB=OPTCD=operand), or at assembly time by the appropriate DCB oper- 
ands. 



i 



354 OS/MFT and OS/MVT TCAM Programmer's Guide 



The POINT macro, used in conjuction with a GET or READ macro, enables the 
user to retrieve a message from a message-queues data set on disk, when this 
message has already been sent to its destination. 

TCAM permits an application program to control a teleprocessing network with 
the TCOPY, ICOPY, COPY, TCHNG, ICHNG, MRELEASE, and MCPCLOSE 
macros. All operator control functions are available from application programs; 
operator commands may be transferred to the MCP by PUT/WRITE macros. 
Responses to operator commands may be directed to any destination queue 
(except a PUT process entry) by the ALTDEST= operand of the PUT process 
entry. 

Application programs written to run with a QTAM Message Control Program can 
be used when conversion is made from QTAM to TCAM. QTAM application 
programs being modified to run under TCAM need only be reassembled with a 
QSTART macro as the first instruction. During execution, the modified appHca- 
tion program operates in most respects as it did under QTAM. Appendix E gives 
details on how to run QTAM application programs under TCAM. 

A TCAM application program is defined as a task containing one or more data 
control blocks opened using data definition statements containing the QNAME= 
parameter. This general definition applies to SAM-compatible and to QTAM- 
compatible application programs prepared to execute in conjunction with a 
TCAM Message Control Program. Therefore, TCAM-related macro instructions 
issued in an application program execute as specified only if the task in which they 
are issued contains an open QNAME data control block. 

One exception to this rule exists. The user may issue a PUT or WRITE from an 
attached task, provided that the task to which it is attached is, by definition, a 
TCAM application program. For example, the attaching task (task A), can open 
the necessary data control blocks required to estabhsh the MCP/application 
program interface and can issue GETs or READs to a process queue. When the 
GET or READ is satisfied, task A analyzes the message and attaches the task 
necessary to process the message. By taking advantage of the exception stated 
above, the attached task can create and PUT or WRITE a response to the mes- 
sage, without a special interface, to return the response to task A for the PUT or 
WRITE. 

Message Flow to an Application Program 

This section describes the flow of a single-segment message between a remote 
station and an application program operating under TCAM with QSAM as the 
SAM interface. The steps described here are repeated for a multisegment mes- 
sage, except that the response message, if any, may be returned by the PUT macro 
any time after the first segment is received. This discussion summarizes message 
flow as discussed in the TCAM Concepts and Facilities, and adds a detail 
unique to application programs, the read-ahead queue. 

A message segment enters the MCP and is placed in a buffer. The segment is 
handled by the incoming group of the MH for the originating station and is placed 
on the destination queue for the application program (called, hereafter, the 
process queue ). 

The segment is then removed from the process queue and handled by the outgoing 
group of the MH for the application program. At this point, the message is 
queued on the read-ahead queue, an area in main storage related to the process 



Writing TCAM-Compatible Application Programs 355 



queue. The read-ahead queue permits overlap of MCP and application-program 
processing of messages queued for a particular destination. This queue allows a 
message to be removed from a process queue to be processed by the outgoing 
group of the MH for the apphcation program at the same time that a message that 
was previously on a process queue is being processed by the application program 
itself. The application program obtains the message from the read-ahead queue by 
GET or READ macro instructions. These macros obtain the messages in sections 
of data, called work units , that will fit in an area of the application program 
called the work area . The message is placed in the work area for processing; the 
size of the work area bears no necessary relationship to the size of the MCP 
buffers. 

After processing, and assuming there is a response message, the message is 
returned to the MCP, where it is placed in buffers. The buffers are handled by the 
incoming group of the MH for the application program and are placed on the 
appropriate destination queue (which may also be a process queue). After 
handhng by the outgoing group of the MH for the destination, the response 
message is either sent on a line to a remote station or transferred to another 
apphcation program. 

Overview of the MCP/Application-Program Interface 

The TCAM MCP routes messages between an application program and remote 
stations. Because an application program depends on the MCP to perform its 
input/output operations, an interface must be established between an apphcation 
program and the MCP. TCAM allows this interface to be established from an 
apphcation program by: 

• definition of the interface (by the apphcation program input and output DCB 
macros and DD statments, and by the PCB and TPROCESS macros in the 
MCP); 

• initialization and activation of the interface (by the OPEN macro); 

• transfer of messages between the application program and the MCP (by GET, 
PUT, READ, WRITE, CHECK, and POINT macro instructions); 

• deactivation of the interface (by the MCPCLOSE and CLOSE macros). 

TCAM also provides buffer facilities specifically designed for the MCP interface. 

Unlike the functions performed by the analysis and processing routines of an 
application program, these functions are partially or wholly peculiar to TCAM and 
the telecommunications environment. Therefore, TCAM provides routines to 
accomplish these functions. Linkage to these routines is estabhshed by TCAM 
and by standard data management macro instructions in an apphcation program. 

Information necessary for communication between the MCP and an application 
program is provided by a control area defined by a PCB macro issued in the MCP 
(note also that the queues for an apphcation program are defined by a 
TPROCESS macro in the MCP). No more than one application program can use 
a process control block, the control area defined by a PCB macro. 

Message transfer from a destination queue to an application program is controlled 
by an input data control block (input DCB). An input DCB defines a logical data 
set called an input data set, which contains the messages being sent to the apphca- 
tion program from a single destination queue created by a TPROCESS macro. If 
response messages are generated, message transfer from the application program 
to the MH queue is handled by another data control block, the output DCB. An 
output DCB defines a logical data set called an output data set, which contains 



356 OS/MFT and OS/MVT TCAM Programmer's Guide 



u 



( 



messages being returned from the application program to the MCP by one process 
entry in the terminal table. (A PUT, GET, READ, or WRITE macro names a 
DCB. The DCB macro specifies a DD statement. The QNAME parameter of the 
DD statement is coded with the name of a process entry. One data set must be 
defined for each process entry designed to receive messages from and send 
messages to an application program.) The user must define, open, and close the 
logical data sets represented by the DCBs. 

A separate process entry must be specified for each input or output DCB in the 
application program. A DD statement must be provided for each such DCB. The 
format of the DD card is indicated later in this section. 

Figure 28 shows how to set up the interface between the MCP and the apphcation 
program by coding macro operands. Only those operands that help establish the 
interface are shown in the figure. 

The GET, PUT, READ, WRITE, PCB, and input and output DCB macros, and 
the DD statements for the input and output DCB macros, are discussed in detail 
in this chapter. The TPROCESS macro is discussed in the Defining Terminal 
and Line Control Areas chapter. The GET and PUT or READ and WRITE macros 
issued in an application program each specify the name of a data control block 
created by an input or output DCB macro. One input DCB macro must be 
coded in the application program for each terminal-table process entry 
named in a destination field in a message header or in an operand of the 



Name 


Operation 


Operand 



f 



f 



mhn 



GET (or READ) 

or 
PUT (or WRITE) dcbname 



>v 



dcbname DCB 



DDNAME=ddname 



ddname DD 



QNAME=procname 



application 
program 



procname TPROCESS 



PCB=pcbname 



>V 



pcbname PCS 



MH=mhname 



STARTMH 

MH for application 
program 



MCP 



J 



Figure 28. Interface between the Application Program and the MCP 



Writing TCAM-Compatible Application Programs 357 



4 

( i 



FORWARD macro to direct messages to the application program. A 
destination queue is created by TCAM for each such process entry. One output 
DCB macro must be coded in the application program for each process entry 
to be associated with response messages entered by the appHcation program. 

Each input or output DCB macro specifies (in its DDNAME= operand) a DD 
statement that must be included as part of the Job Control Language for execu- 
tion of the appUcation program. This DD statement has a QNAME= parameter 
that specifies the name of a process entry in the terminal table of the MCP. The 
TPROCESS macro that creates each process entry has a pcbname operand, which 
names a PCB macro. The PCB macro names an MH to handle messages being 
sent to or received from the application program by process entries whose 
TPROCESS macros name this PCB macro. The PCB macro is similar to the line 
group DCB macro in that both specify Message Handlers and other related values. 
The MH specified by the hne group DCB macro handles messages transmitted 
between remote stations and the computer, while the MH specified by the PCB 
macro handles messages sent to and received from the appHcation program by the 
MCP. 

Defining the Components of the Interface 

Among the components of the MCP/application program interface are: 

• process entries located in the terminal table and referred to by GET/READ 
and PUT/WRITE macros; 

• data control blocks (and DD statements) for the appHcation-program input and 
output data sets; 

• the process control block (this block specifies the MH for the appUcation 
program); 

• buffers to transfer data between the MCP and the appUcation-program work 
areas. 

Process entries are created by TPROCESS macros (described in the chapter 
Defining Terminal and Line Control Areas). The other components of the 
interface are described in this section. 

Defining the Application Program Data Sets and the Process Control Block 

Two types of logical data sets, called the input data set and the output data set, 
must be defined when writing a TCAM application program. 

The input data set consists of the data (messages or records) sent to an application 
program from a single destination queue created by a TPROCESS macro (process 
queue). An input data set is defined by an input DCB macro. One input data set 
should be defined for each process queue. 

The messages or records in an input data set are transferred from the process 
queue to the application program by a GET or READ macro that specifies the 
name of the input data set. 

An output data set contains the messages or records returned from the appUcation 
program to the MCP by a process entry in the terminal table. An output data set 
is defined by an output DCB macro. One output data set must be defined for 
each process entry designed to receive messages from an application program. 
Messages are transferred from the appUcation program to the MCP by a PUT or ^ 

WRITE macro specifying the name of the output data set. w 



358 OS/MFT and OS/MVT TCAM Programmer's Guide 



The line group DCB macro for the MCP names the Message Handler that is to 
handle messages sent over any line in the Hne group for which it is issued. For the 
application program, this function is performed by the PCB macro rather than by 
the input or output DCB macro. One and only one PCB macro must be coded for 
each application program that is to interface with the MCP. This macro is coded 
in the MCP rather than in the application program. In addition to assigning an 
MH to the application program, the PCB macro specifies the size of the buffers to 
be assigned by the MCP to handle messages being sent to and received from that 
application program. 

The next sections describe the input and output DCB macros, the DD statements 
required for these macros, and the PCB macro. Many operands of the input and 
output DCB macros are concerned with aspects of data transfer and processing 
(type of record, type of work area, etc.); these operands should not be coded until 
Transferring Data Between an MCP and an Application Program in this 
chapter has been read. 



Writing TCAM-Compatible Application Programs 359 



i 



dcbname 



keyword operands 



Input DCB Macro 



The input DCB macro 

• defines an input data set for an application program; 

• must be issued for each process queue to which access is gained by the appUca- 
tion program with GET or READ macros; 

• specifies whether BSAM or QSAM is to be used to transfer messages or records 
from the MCP to the application program; 

• specifies the length in bytes of the appUcation-program work area to which data 
is transferred from the MCP; 

• specifies the length in bytes of buffers to be used in the MCP to transfer 
messages from the process queue to the appHcation-program interface; 

• specifies whether the application program is to handle entire messages or 
message portions called logical records; 

• specifies the format and characteristics of records in the input data set; 

• indicates the address of a routine to be given control when the end of a user- 
defined series of data records is reached; 

• indicates the address of a routine to be given control when message overflow 
occurs. 

The input DCB macro allocates main-storage space for a data control block at 
assembly time. Parameters based on the operands specified in the macro are 
included in the data control block. The macro generates no executable code. One 
(and only one) input DCB macro is coded for each process queue to which the 
application program may direct a GET or a READ macro. Only one application 
program and one GET or READ macro may refer to a process queue at any time. 
(The GET or READ specifies the name of the input DCB macro; the DCB macro 
names a DD statement; the DD statement names a process entry in the terminal 
table.) 

The input DCB macro has the following format: 



Name 


Operation 


Operands 


dcbname 


DCB 


keyword operands 



Function: Specifies the name of the macro instruction and also the name of the 

data control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the operands that can be used. 

Format: May be specified in any order, separated by commas with no intervening 

blanks. 

Notes: The operands are described below. 

When a parameter can be provided by an alternate source, an appropriate symbol 



Writing TCAM-Compatibie Application Programs 361 



DSORG*PS 



MACRF* 



R [P] 



appears below the operand associated with that parameter. When there is no 
alternate source (that is, the parameter must be specified by the operand), no 
symbol is shown. The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be omitted from the DCB macro and 

provided at execution time by the Data Definition (DD) card for the data 
set. 

OE The value of the operand can be provided by the problem program any 
time up to and including the data control block exit at open time. 

PP The value of the operand can be provided by the user's problem program 
any time before open time. 

If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. 

For information on how to provide parameters by means of OE or PP, see Data 
Management Services . The same publication describes the data control block exit 
that can be taken when OE is specified. Information on providing parameters by 
DD is given below in the section DD Statements for the Input and Output 
Data Sets. 



Alternate Source: None. 

Function: Specifies that the data control block governs message transfer to and 

from a destination queue, and identifies the data set organization as physical 

sequential. 

Default: None. This operand is required. 

Format: DSORG=PS 

Notes: This operand achieves TCAM compatibility with QSAM or BSAM. 



Alternate Source: None. 

Function: Specifies the type of access to the destination queue. 

Default: None. This operand is required. 

Format: GM, GMT, GL, GLT, R, RP 

Notes: G indicates GET (QSAM), R indicates READ in move mode (BSAM). 

GET is in move (M) or locate (L) mode. 

The optional T permits the POINT macro to be used in conjunction with GET and 
is required if POINT is to be used with GET. 

The optional P permits the POINT macro to be used in conjunction with READ 
and is required if POINT is to be used with READ. 



If locate mode (L) is specified for a GET, TCAM obtains a work area by the 
GETMAIN macro instruction at OPEN time from the appUcation program main 
storage. TCAM returns the address of the work area in register 1 following the 
first GET macro and uses this work area for succeeding GETs (see Dynamic 
Work' Area Definition in this chapter). Locate mode is inconsistent with BSAM. 



< 



362 OS/MFT and OS/MVT TCAM Programmer's Guide 



DDNAIVlE=svmbol 



BLKSIZE=mteger 



BUFL=lnteger 



LRECL=integer 



RECFIV1= 



F 

V[B] 

U 



Alternate Source: PP. 

Function: Specifies the name of the DD statement associated with the data 

control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is omitted, it must be provided by the alternate source. 



Alternate Source: DD. 

Function: Specifies the size in bytes of the application program work area. 

Default: None. This operand is required. 

Format: Unframed decimal integer no smaller than the length of a record as 

specified by the LRECL= operand. 

Maximum: 32760 

Notes: If this operand is omitted, it must be provided by the alternate source. 

The length of optional fields in the work area must be included in the value 
specified for this operand. TCAM uses this field to determine the length of the 
work area. 

For undefined-format work units, the value specified for BLKSIZE= may be 
dynamically overridden on a work-unit-by-work-unit basis by the length operand 
of the READ macro. 



Alternate Source: None. 

Function: Specifies the size in bytes of buffers used in the MCP for messages 

coming to the application program associated with this DCB macro. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the value specified in the BUFSIZE= operand 

of the PCB macro is used. 



Alternate Source: DD. 

Function: Specifies the number of bytes for a record, plus the length of any 

optional fields in the work area. 

Default: If RECFM=F, this operand is required. Otherwise, specification 

optional. 

Format: Unframed decimal integer. 

Maximum: 32760 

Notes: If RECFM=U is specified, the LRECL= field in the input DCB is 

updated after each GET or READ macro with the sum of the number of bytes of 

data fetched by that GET or READ, plus the length of any optional fields in the 

work area. 



Alternate Source: DD. 

Function: Specifies the format and characteristics of the work units in this input 

data set. 

Default: RECFM=U 

Format: F, V, VB, or U. 



Writing TCAM-Compatible Application Programs 363 



OPTCD=[WHLfl(Cl 



Notes: V specifies that the work units are variable in format. For BSAM and 
QSAM, each work unit is prefaced in the work area by a standard SAM four-byte 
prefix (all entries in the prefix are in hexadecimal format). 

VB specifies that the work units are treated as blocked, although only one work 
unit is transferred per GET or READ. The variable-length work unit work area 
includes a blocked work area prefix of eight bytes if MACRF=R is specified, and 
of four bytes if not. 

U specifies undefined-format work units. TCAM, like SAM, provides no prefix. 
The length of the work unit is stored by TCAM in the LRECL= field in the input 
DCB. TCAM updates the LRECL= field after each GET or READ with the 
length of the work unit. 

F specifies fixed-length work units. The sum of the length of each work unit 
obtained plus the length of any optional fields in the work area is specified by the 
user in the LRECL= field of the input DCB and may be updated before each 
GET or READ. This option should be used only when the number of bytes of 
data in a message is an exact multiple of the number of bytes specified by the 
LRECL= operand. Otherwise, the last portion of the message contains fewer 
bytes than the number specified in the LRECL= operand, and the program would 
have to be capable of handling this smaller portion of the message. 



Alternate Source: DD. 

Function: Specifies the optional fields for the work unit. 

Default: None. Specification optional. 

Format: W, WIJ, WC, WUC, U, UC, C. 

Notes: W specifies that the name of the source of each message is to be placed in 

an eight-byte origin field in the work area. TCAM places the narjie of the source, 

in EBCDIC, in the field, left-adjusted and padded to the right with blanks. If W is 

coded but TCAM cannot determine the message source, the field is filled with 

eight, character blanks. 

U specifies that the work unit to be handled is either a message or a message 
segment that is not a record. If U is omitted, the work unit is assumed to be a 
record. 

C specifies that a one-byte field in the work area, called the position field, is to 
indicate whether the work unit being handled is the first, an intermediate, or the 
last segment of the message and whether a record delimiter has been detected in 
the data. If the application-program user specifies OPTCD=C on his DCB 
macro, a one-byte position field in the work area is used to describe the work unit. 
The control byte is defined as follows: 



< 



364 OS/MFT and OS/MVT TCAM Programmer's Guide 



Position Field 

XTl' (1) 

X'40' (blank) 

XT2' (2) 

XT3' (3) 



Work Area Contents 

First portion of message 
Intermediate portion of message 
Last portion of message 
An entire message 



In addition, if the user specified RECFM=U (undefined-length work units) or 
RECFM=V (variable-length work units), and OPTCD=C or CW, the control 
byte may have the following contents: 

Position Field Work Area Contents 

XT5' (5) First portion of message, end-of -record 

XT4' (4) Intermediate portion of message, end-of-record 

XT6' (6) Last portion of message, end-of-record 

XT7' (7) An entire message, end-of-record 

The control byte may have one of the four values above only if the record delimi- 
ter specified on the TPROCESS macro is the last byte of data in the work unit. 



EODAD=address 



SYNAD=address 



EXLST=address 



) 



Alternate Source: PP. 

Function: Specifies the address of an open or closed subroutine to be given 

control after the access method recognizes a user-generated, end-of-file indication 

in the header of a message. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: TCAM takes this exit when the next GET or CHECK macro is issued 

following complete transfer of the end-of-file message into the work area. 



Alternate Source: PP. 

Function: Specifies the address of an open or closed subroutine to be given 

control if message processing is used, the work unit is larger than the work area, 

and OPTCD=C is not specified. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: For more information on the SYNAD exit, see Application Program 

Error Exit in this chapter. 



Alternate Source: PP. 

Function: Specifies the address of the problem-program exit Ust. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The list must start on a fuUword boundary; its format and contents are 

more fully shown in Data Management Services . Each entry is a fuUword made 

up of a control byte followed by the three-byte address of a user- written routine. 

Only two entries in the Ust (those having control bytes of X'05' and X'OF') are 
meaningful for a TCAM input DCB. 

The entry having a control byte of X'05' is the DCB exit entry, it is explained in 
the Data Management Services publication. 



Writing TCAM-Compatible Application Programs 365 



If the control byte is X*OF', the user-written routine is given control to initiate an 
OS checkpoint of the appUcation program (see the section on coordinating OS and 
TCAM checkpoints in this chapter). 

Upon entry to the routine specified by the exit-list entry, the contents of registers 
and 2 through 13 are the same as they were just before the GET or CHECK 
macro was executed. Register 1 contains the address of this input DCB, while 
register 14 contains the return address for the application program. The user 
routine must save and restore the contents of registers 1 and 14. The contents of 
the user-defined save area must not be altered by the exit routine. 



STOP= (QUICK 
\ FLUSH 
I BOTH 



Function: Specifies type of MCPCLOSE and SYSCLOSE. 

Default: None. Specification optional. 

Format: STOP=QUICK; STOP=FLUSH; STOP:=BOTH. 



QUICK specifies that the EODAD exit of the input DCB macro is to be taken on 
a quick close. FLUSH specifies that the EODAD exit is to be taken on a flush 
close. BOTH specifies that the EODAD exit is to be taken on either type of 
closedown. If the STOP= operand is coded, the EODAD= operand must also be 
coded. 

Note: This operand is for defining the action to be taken if closedown is issued 
while an application program is executing. 



366 OS/MFT and OS/MVT TCAM Programmer's Guide 



Output DCB Macro 



The output DCB macro 

• defines an output data set for an application program; 

• must be issued for each process entry set up to receive messages or logical 
records from an application program; 

• specifies whether QSAM or BSAM is to be used to transfer messages or logical 
records from the application program to the MCP; 

• specifies the format and characteristics of records in the data set; 

• specifies the length of the MCP buffers used to receive messages from this 
apphcationpr ogr am ; 

• specifies the address of a routine to be given control when logical output errors 
occur; 

• specifies the address of the problem-program exit list. 

The output DCB macro has the following format: 



Name 


Operation 


Operands 


dcbname 


DCB 


keyword operands 



dcbname 



Function: Specifies the name of the macro instruction and the name of the data 

control block operated on by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



Function: Specifies the operands that may be used. 

Format: May be specified in any order, separated by blanks with no intervening 

commas. 

Notes: The operands are described below. 

When a parameter can be provided by an alternate source, an appropriate symbol 
appears below the operand associated with that parameter. When there is no 
alternate source (that is, the parameter must be specified by the operand), no 
symbol is shown. The symbols have the following meanings: 



Symbol 



Explanation 



DD The value of the operand can be provided at execution time by the Data 
Definition (DD) card for the data set. 

OE The value of the operand can be provided by the problem program any 
time up to and including the data control block exit at open time. 

PP The value of the operand can be provided by the user's problem program 
any time before open time. 






If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. 



Writing TCAM-Compatible Application Programs 367 



For information on how to provide parameters by one of these alternate sources, 
see the note following the explanation of DD, OE, and PP in the discussion of the 
input DCB macro. 



DSORG=PS 



DDNAME=symbol 



IV1ACRF= iP^IVI 

[W 



Alternate Source: None. 

Function: Specifies that the data control block governs message transfer to or 

from an application program, and identifies the data set organization as physical 

sequential. 

Default: None. This operand is required. 

Format: DSORG=PS 

Notes: This operand achieves TCAM compatibility with QSAM and BSAM. 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is omitted, it must be specified from the alternate source. 



Alternate Source: None. 

Function: Specifies the method by which messages are to be transferred to the 

destination queue. 

Default: None. This operand is required. 

Format: PM, PL or W. 

Notes: P specifies that messages are to be transferred by PUT macros. W 

specifies that messages are to be transferred by WRITE macros. 



4 



BLKSIZE^integer 



PUT may be in move (M) or locate (L) mode. WRITE imphes move mode. 

If locate mode (L) if specified for PUT, TCAM obtains a work area by the 
GETMAIN macro instruction when the first PUT is executed. TCAM returns the 
address of the work area in register 1 following the first PUT (see Dynamic 
Work Area Definition in this chapter). 



Alternate Source: DD. 

Function: Specifies the size in bytes of the application program work area. 
Default: None. If locate mode is not specified, specification optional. Other- 
wise, this operand is required. 

Format: Unframed decimal integer no smaller than the length of a work unit. 
Maximum: 32760 

Notes: The length of any optional fields in the work area should be included in 
the value specified for this operand. If locate mode is specified by the MACRF= 
operand and this operand is omitted, it must be specified by an alternate source. 



LRECL=lnteger 



Alternate Source: DD. 

Function: Specifies the sum of the number of bytes in the length of a fixed- or 
undefined-length work unit, plus the length of any optional fields in the work area. 
Default: If RECFM=F is specified, this operand is required. Otherwise, specifi- 
cation optional. 



c 



368 OS/MFT and OS/MVT TCAM Programmer's Guide 



OPTCD=[W][U][C] 



SYNAD=address 



Format: Unframed decimal integer. 
Maximum: 32760 

Notes: If RECFM=U is specified and no work-unit length is specified by the 
length operand of the WRITE macro, the contents of the field must be updated 
dynamically by the program before a PUT or WRITE macro is issued; user code 
must place the number of bytes of data in the work area (including optional fields) 
into the LRECL= field of the DCB. This may be done with the aid of the DCBD 
macro, described in Supervisor and Data Management Macro Instructions . 

If a value is specified by the length operand of the WRITE macro, this value 
overrides the value specified in the LRECL= field for undefined work units. 



Alternate Source: DD. 

Function: Specifies the type of optional field to l?e used. 

Default: None. Specification optional. 

Format: W, WU, WC, WUC, U, UC, C. 

Notes: W specifies that the program must place the name of the destination of the 

message in an eight-byte destination field in the work area before a PUT or 

WRITE macro is executed. If a FORWARD macro with the operand 

DEST=PUT is coded in the incoming group of the appUcation-program Message 

Handler, the message is routed to the destination specified in this field. 

U specifies that the work unit is a message or a portion of a message that is not a 
record; if U is omitted, the work unit is assumed to be a record. 

C specifies that a one-byte position field in the work area is used to describe the 
position of the work unit in the message of which it is a part. The control byte is 
defined as follows: 



Position 


Field 


Work Area Contents 


X'Fl' 


(1) 


First portion of message 


X'40' 


(blank) 


Intermediate portion of i 


XT2' 


(2) 


Last portion of message 


X'F3' 


(3) 


An entire message 



Alternate Source: PP. 

Function: Specifies the address of a routine to be given control when logical 

output errors occur. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: For more information on this routine, see Application Program Error 

Exit in this chapter. 



Writing TCAM-Compatible Application Programs 369 



RECFM= 



^ V[B] 



EXLST=address 



Alternate Source: DD. 

Function: Specifies the format of the work units in this output data set. 
Default: RECFM=U 
Format: F, V, VB, or U. 

Notes: V specifies that the work units are variable in length. For BSAM and 
OSAM, each work unit is prefaced in the work area by a standard SAM, variable- 
length record prefix of four bytes (the contents of which are in hexadecimal 
format). The length of the work unit must be provided by setting up the prefix 
before issuing a PUT or WRITE macro. 

If RECFM=VB, the records are treated as blocked, although only one work unit 
is transferred to the MCP per PUT or WRITE macro. The variable-length record 
work area includes a blocked work area prefix of eight bytes if MACRF=W is 
specified, and four bytes if otherwise. 

U specifies undefined-length work units. TCAM, like SAM, provides no prefix. 
The sum of the length of the work unit plus the length of any optional fields in the 
work area must be placed in the LRECL= field of the DCB before each PUT or 
WRITE, unless it is specified by the length operand of the WRITE macro. 

F specifies fixed-length work units. Before the PUT or WRITE, the sum of the 
length of the work unit plus the length of any optional fields in the work area must 
be placed in the LRECL= field of the output DCB. 



Alternate Source: PP. 

Function: Specifies the address of the problem-program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The description of this operand is the same as that provided above for the 

EXLST= operand of the input DCB macro. 



BUFL=mteger 

Alternate Source: DD. 

Function: Specifies the size in bytes of the MCP buffers that are to receive 

messages coming from this application program. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the value specified in the BUFSIZE= operand 

of the PCB macro in the MCP is the value used. 

DD Statements for the Input and Output Data Sets 

At application-program execution time, one DD statement must be provided for 
each DCB. The DD statement has the following format: 

//ddname DD QNAME=procname 



( 



370 OS/MFT and OS/MVT TCAM Programmer's Guide 



ddname 

Is the symbolic name of the DD statement, and must be the same as the name 
specified in the DDNAME= operand of the input or output DCB macro. 

procname 

Is the name of the process entry in the terminal table to which this entry refers. 
This name is assigned by the TPROCESS macro creating the entry. The destina- 
tion queue may be changed at execution time by specifying a different value for 
the QNAME= parameter. 

The following DCB operands may be omitted from the input or output DCB 
macro and coded as parameters of the DD statement when the operand's func- 
tions are to be provided by an alternate source. These operands are explained in 
the discussion of the input and output DCB macros. More than one operand can 
be specified in one DCB= parameter; multiple operands should be separated by 
commas. 

[,DCB=( [BLKSIZE=integer] [ , LRECL=integer ] 
[ ,BUFL=integer] 
[,OPTCD=[W] [U] [C] ] 
[ , RECFM= ( U ) ] )] 

V[B] 

F 



Writing TCAM-Compatible Application Programs 371 



PCB Macro 



The PCB macro 

• provides a control block in the MCP to interface with an application program; 

• is required for each application program running with the MCP; 

• is coded in the MCP, not the application program. 

The PCB macro generates a named control block, known as a process control 
block (PCB). A process control block provides information needed to communi- 
cate between the MCP and an apphcation program. One and only one PCB 
macro is required for each active application program, although the user may 
assign more than one PCB to a single apphcation program. A PCB may not be 
shared by two active application progranis since a PCB is an inter-task control 
block. 

The PCB macro has the following format: 



pcbname 



Name 


Operation 


Operands 


pcbname 


PCB 


MH=mhname, BUFSIZE=size 
[,BUFIN=Jnumbern[,BUFOUT=Jnumbern 

h s 'if 

[,RESERVE= (integer 1 ,integer2)] 
[,DATE=| YES / ] 
' NO ^ 






Function: Specifies the name of the macro and the name of the process control 
block generated by the macro referred to in the TPROCESS macro. 
Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). 



IVIH=mhname 



BUFSIZE=integer 



Function: Specifies the symbolic address of the Message Handler for the applica- 
tion program represented by this macro. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name specified in the name field of a STARTMH macro in the 
Message Handler. 



Function: Specifies the size of the buffers to be assigned to handle messages for 

the associated application program. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than 35. 

Maxim um : 65535 

Notes: This value may be overridden by specifying the BUFL= operand of the 

input or output DCB for the apphcation program. 



I 



372 OS/MFT and OS/MVT TCAM Programmer's Guide 



BUFIN=|nuniber> 



BUFOUT= J number) 



Function: Specifies the initial number of buffers requested into which the data in 

the user's PUT/WRITE work area will be emptied. 

Default: BUFIN=2 

Format: Unframed decimal integer greater than 1. 

Maximum: 15 

Notes: The optimum number specifies enough buffers to contain the entire work 

area. 



Function: Specifies the initial number of buffers that may be filled in anticipation of 

a GET or READ. 

Default: BUF0UT=2 

Format: Unframed decimal integer greater than 1 . 

Maximum: 25 

Notes: Used as a read-ahead queue for a process entry. 



RESERVE=(integerl ,mteger2) 



Function: Specifies the number of bytes to be reserved in buffers. 
Default: None. Specification optional. 
Format: Unframed decimal integers. 
Maximum: 255 for each. 

Notes: integerl specifies the number of bytes to be reserved in the buffer receiv- 
ing the first incoming segment of each message entered by an application pro- 
gram; the space is reserved for insertion of data by DATETIME and SEQUENCE 
functional MH macros. 

integerl specifies the number of bytes to be reserved in all buffers, except the first, 
for insertion of characters by the DATETIME macro, integerl is relevant only in 
a multiple- buffer header situation when the DATETIME macro is to insert data in 
a portion of the header that is not in the first buffer (see the description of the 
DATETIME macro for an example of when it might be desirable to execute 
DATETIME on a portion of the header not located in the first segment). 

Data may be inserted in either an incoming or an outgoing message header, but 
space must be reserved in the incoming header. On the outgoing side, reserved 
space is retained for the first buffer only; thus, DATETIME and SEQUENCE 
macros, if specified in an outheader subgroup, operate only on the first segment of 
the message. 

No space need be reserved for data inserted by a MSGEDIT functional MH 
macro. 



) 



The Scan Pointer section of the chapter Designing a Message Handler de- 
scribes how TCAM handles reserve bytes. Each buffer containing header data 
should be large enough to accommodate the segment itself plus any data that may 
be inserted by DATETIME and SEQUENCE macros. If a buffer containing 
header data does not have a sufficient number of bytes reserved in it to accommo- 
date data inserted by a DATETIME or SEQUENCE macro, the macro does not 
execute and control passes to the next instruction in the MH. Unused reserve 
bytes are not sent out with an outgoing message segment when it is sent to its 
destination. 



Writing TCAM-Compatible Application Programs 373 



DATE= I YES ( 
<NO S 

Function: Specifies whether the date and time of each message received for the 
process entry are to be recorded. 
Default: DATE=NO 
Format: YES or NO. 

Notes: When a message is received for the appUcation program, TCAM records 
the date and time. When the application program issues a GET or a READ 
macro, TCAM places the recorded date/time and the source of the message in the 
area specified by the DTSAREA= operand of the TPDATE macro. 

This operand requires that the DATE= operand also be specified on the 
TPROCESS macro for this process entry. 

Defining Buffers for the Application Program 

Messages being transferred between the appHcation program work area and the 
MCP reside in buffers, as do messages being transferred between the MCP and a 
remote station. The buffers for transferring data to and from the application 
program are ordinary TCAM buffers, described in Defining Buffers, That 
chapter should be read and understood by the programmer responsible for defin- 
ing the application-program buffers, as the structural description and most of the 
design considerations in that chapter can also be used for application-program 
buffers. 

Buffers used to transfer data between an application program and an MCP differ 
from those assigned to a line in two respects: 

• the way in which they are defined; 

• the manner in which they are allocated. / 

The next section describes appUcation-program buffer definition. The following 
section describes the allocation scheme for application-program buffers as part of 
a discussion of appUcation-program buffer design considerations. 

Defining Application-Program Buffers 

A buffer-definition checkUst for the appUcation-program buffers follows. Guide- 
lines for coding many of the operands shown are given in the next section. 

Macro Operand Description of Function and Comments 

INTRO KEYLEN= integer Specifies the bytes in a buffer unit; all buffers in 

the TCAM system are constructed of units of 
this size. (Considerations for coding this oper- 
and are given in the ohz^tQi Defining Buff ers ) 
integer must be between 35 and 255 inclusive. 

PCB BUFSIZE= integer Specifies the size in bytes of the buffers used to 

transfer message segments between the process 
queues for the application program and an 
application-program work area. May be overridden 
for a single input or output data set by the 
BUFL= operands of the input or output DCB 
macro for that data set. integer must be between 
35 and 65535 inclusive. 



i 



i 



374 OS/MFT and OS/MVT TCAM Programmer's Guide 



[BUFOUT=dntegern 



h 






[BUFIN=untegern 



Specifies the maximum number of 
application-program buffers that may be 
filled from the destination queue, 
processed by the outgoing group of the 
application-program MH, and placed on the 
read-ahead queue in main storage in anticipation 
of a GET or READ macro, integer must be at 
least 2 (TCAM uses one buffer internally) and 
may be no greater than 25. 

Specifies the initial number of buffers to 

be allocated to receive data being 

transferred by a PUT or WRITE 

macro from the application-program work area 

to the MCP. integer may be between 2 and 15 

inclusive. 



Input [BUFL=integer] Specifies the size in bytes of the buffers 

DCB to be used to transfer message segments 

from the MCP to the 

application program; overrides the value speci- 
fied by the BUFSIZE= operand of the PCB mac- 
ro, integer must be between 35 and 65535 in- 
clusive. 



Output [BUFL=integer] 
DCB 



Specifies the size in bytes of the 
buffers to be used to transfer message segments 
from the appUcation program to the MCP; over- 
rides the value specified by the BUFSIZE= oper- 
and of the PCB macro, integer must be between 
31 and 65535 inclusive. 



Application-Program Buffer Design Considerations 

The user assigns a maximum number of buffers (with the BUFOUT= operand of 
the PCB macro) that can be used at one time to handle messages being transferred 
from MCP process queues to the appHcation-program work area. These buffers 
are used to construct the read-ahead queue . The read-ahead queue is discussed in 
Message Flow to an Application Program in this chapter. TCAM constructs 
one read-ahead queue for each process queue associated with an opened input 
data set. 

The maximum capacity of a read-ahead queue is two messages. Buffers are 
allocated to this queue dynamically, but the queue never contains more than the 
number of buffers needed to handle two messages. If the user specifies (with the 
BUFOUT= operand of the PCB macro) a number of buffers less than that needed 
to contain two entire messages on the read-ahead queue, less main storage is tied 
up by being assigned to the read-ahead queue, but more time is required to 
transfer messages to the application program. 



The following formula for calculating the BUFOUT= operand of the PCB macro 
provides a read-ahead queue always capable of containing two complete mes- 
sages; by specifying a queue of this size, the user minimizes delay in transferring 
messages to the application program. 

I=2X-Hl 



Writing TCAM-Compatible Application Programs 375 



Here / represents the integer to be coded for BUFOUT=, and X is the maximum 
number of buffers needed to hold one message being transferred to the appUcation 
program. The extra buffer represented by 1 is used internally by TCAM. 

If main-storage-only queuing is the sole type of queuing used for process queues, 
the optimum number of buffers specified by BUFOUT= is reduced; in this case, 
one need specify only enough buffers to handle the largest work unit to be sent to 
the appHcation program for optimal performance of read-ahead queues. 

The BUFIN= operand of the PCB macro specifies the initial number of buffers to 
be allocated to receive data being transferred by a PUT or WRITE macro from 
the application program to the MCP. (If there is more than one appUcation- 
program process entry that may be referred to by PUT or WRITE macros, the 
number of buffers specified by BUFIN= is allocated to each.) Buffers assigned to 
receive data from the application program are deallocated and sent through the 
incoming group of the apphcation-program message handler as they are filled. 

If the number of buffers specified by BUFIN= is not sufficient to handle the 
entire work unit being transferred, TCAM dynamically allocates additional 
buffers. However, such allocation takes time; to optimize performance, a suffi- 
cient number of buffers should be assigned initially to handle the entire work unit. 

The size of the apphcation-program buffers is specified by the BUFSIZE= 
operand of the PCB macro. This size may be overridden for buffers handling data 
being transferred to the application program by the BUFL= operand of the input 
DCB macro, and for buffers handling data being transferred from the application 
program by the BUFL= operand of the output DCB macro. 

Buffer size considerations given in the chapter Defining Buffers are relevant to 
application-program buffers (considerations in that chapter that deal with 
program-controlled interruptions (PCI) are an exception). 

Buffers are sent through the incoming group of the application-program MH as 
soon as they are filled. If a buffer is not filled when the end of the work unit is 
reached, either a time or a space penalty will be incurred, depending upon whether 
a position field is present in the work area, and upon whether message- or record-^ 
processing is specified. (Position fields are discussed in Defining Optional 
Fields in the Work Area in this chapter. Message and record processing are 
described in Specifying Application-Program Work Units .) 

If no position field is present and message processing is specified, the partially 
filled buffer is sent through the incoming group of the application program as soon 
as the last portion of the work unit has been received. In this case a space penalty 
is incurred and main storage is wasted, since the entire buffer is tied up while the 
work unit is being processed by the incoming group. If record processing is 
specified and there is no position field, a buffer that is larger than the work unit it 
contains is not sent through the incoming group immediately, but is held until it is 
filled by a subsequent PUT or WRITE (or until the application-program signals 
end-of-message by closing the output data set); in this case, a time penalty is 
incurred. 

If a position field is present and indicates that the current work unit is the last or 
only work unit in the message, the buffer containing that work unit is sent through 
the incoming group as soon as the work unit is placed in it; if the work unit is 
shorter than the buffer, main-storage space is wasted, as explained above. If the 



c 



376 OS/MFT and OS/MVT TCAM Programmer's Guide 



position field indicates that the current work unit is the first or an intermediate 
unit in a multi-unit message, then the buffer is not sent through the incoming 
group until it is filled or until the end of the message is encountered; if the work 
unit is smaller than the buffer, a time penalty is incurred, as explained above. 

When the buffer sizes specified for the origin and the destination of a message are 
different, data movement occurs because prefixes must be added or deleted when 
the message is placed in the buffers for the destination (this is discussed in the 
chapter Defining Buffers ). Because data movement takes time, the buffer size 
for line buffers handling messages being sent to or from an application program 
should be the same as the buffer size for the application-program buffers 
wherever possible. By overriding the buffer size specified by the BUFSIZE= 
operand of the PCB, the BUFL= operand of the input and output DCB macros 
may be used to tailor application-program buffer sizes to buffer sizes for particu- 
lar origin or destination stations. 

For example, if line buffers for all stations that could enter and accept messages 
processed by a particular application program were either 116 bytes or 232 bytes, 
the user could define two input and output data sets (each with its own 
GET/READ and PUT/WRITE process entries), one for each buffer length. He 
could direct all incoming messages for the application program that were entered 
by stations using 1 16-byte buffers to one process queue, and all incoming mes- 
sages for the appHcation program that were entered by stations using 232-byte 
buffers to the other process queue. If he coded BUFSIZE= 1 16 in his PCB macro 
and BUFL=232 in the input DCB macro for the data set containing messages 
placed in 232-byte buffers upon arrival at the computer, no data transfer would be 
necessary when the data was read from the destination queue into application- 
program buffer. 

When transferring responses from the application program, the user would name 
the PUT/ WRITE process entry for the 1 16-byte-buffer output data set or for the 
232-byte-buffer output data set, depending upon the size of the line buffers for 
the destination station. In the output DCB for the 232-byte-buffer output data 
set, he would specify BUFL=232. Again, no data transfer would be necessary 
when messages were read from the destination queues into the line buffers for the 
destination station if this scheme were followed. 

Activating and Deactivating the Application-Program Interface 

Activation and deactivation of the interface between an application program and 
the MCP is handled by OPEN, CLOSE, and MCPCLOSE macro instructions. 
The OPEN and CLOSE macros for TCAM-compatible application programs are 
used and coded in the same way as OPEN and CLOSE macros coded for applica- 
tion programs in a non-teleprocessing environment and are described in the 
Supervisor and Data Management Macro Instructions publication. List and 
execute forms may be coded for OPEN and CLOSE. The user may code options 
for the OPEN and CLOSE macros shown in Supervisor and Data Management 
Macro Instructions to run his application program in a non-teleprocessing envi- 
ronment for debugging purposes; when the program is run in a TCAM environ- 
ment, the option fields are ignored. More than one data set may be opened or 
closed with the same application-program OPEN or CLOSE macros. The OPEN, 
CLOSE, and MCPCLOSE macros are described in this present section. Deactiva- 
tion of the application program is discussed in the chapter Activating and 
Deactivating the Message Control Program . 



Writing TCAM-Compatible Application Programs 377 



OPEN (application program) 



The OPEN macro for the apphcation program 

• completes initialization and activation of the input and output data sets for the 
application program; 

• is required to activate each data set represented by an input or output DCB 
macro. 

Initialization and activation of the interface to the MCP is accomplished by issuing 
one or more OPEN macros to open the data sets represented by the input and 
output DCB macros. 

One input DCB macro must be coded for each process queue for an application 
program (that is, each queue for which messages can be obtained by GET or 
READ macros). One output DCB macro must be coded for each process entry 
that can be referred to by a PUT or WRITE macro when a work unit is being 
transferred from the apphcation program to the MCP. 

The open routines in TCAM activate the interface between the MCP and the 
apphcation programs. No TCAM macro instructions in the apphcation program 
may be successfully executed before the DCB for the message queues data set has 
been opened in the MCP or after it has been closed (if disk queuing is used), or 
before the input and output data sets are opened or after they are closed. After 
the message queues data sets on disk and application-program data sets have been 
opened, transfer of data to and from the application program can commence. 

The operand field of the OPEN macro consists of one or more postitional ope- 
rands, followed by a single keyword operand. Each positional operand consists of 
the name of the data control block for the data set being opened (the name of the 
block is the name of the DCB macro that created it). A comma is coded between 
names. The optional keyword operand at the end permits the hst and the execute 
form of the macro to be specified. 

The OPEN macro for the application program has the following format: 



symbol 



Name 


Operation 


Operands 


[symbol] 


OPEN 


(dcbname„...)[,MF=(L )] 
\(E,listname)j 



Function: Specifies the name of the macro. 

Default: None. If MF=L is coded, this name is required. Otherwise specifica- 
tion optional. 

Format: Must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). 

Notes: If MF=L is specified, this name becomes the name of the parameter hst 
generated by this macro. 



i 



378 OS/MFT and OS/MVT TCAM Programmer's Guide 



(dcbname„.») 



MF= 



i (EJistname) ) 



Function: Specifies the name of the data control block and is identical to the 

name specified in the symbol field of the DCB macro for the data set being 

opened. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: Register notation may be used, in which case the specified register (2 

through 12) should contain the address of the data control block for the data set 

being opened. The specified register number must be enclosed in parentheses. If 

more than one dcbname is specified, they must be separated by double commas. 



Function: Specifies that a list is to be created, or that a previously created list is 

to be opened. 

Default: None. Specification optional. 

Format: listname must conform to the rules for assembler language symbols. 

Notes: MF=L causes creation of a parameter list based on the OPEN operands. 

No executable code is generated. The user must specify this form of the OPEN 

among his program constants. The parameters in the hst are not used until the 

problem program issues an OPEN (or CLOSE) macro with an MF=(E, listname) 

operand that refers to the list. The name specified in the name field becomes the 

name assigned to the parameter list. 

MF=(E,listname) causes execution of the OPEN routine, using the parameter list 
referred to by listname . This list was created by a macro having the MF=L 
operand specified. Parameters specified in a macro having the MF=(E,listname) 
operand override corresponding parameters in the Hst. 



Writing TCAM-Compatible Application Programs 379 



CLOSE (application program) 



symbol 



(dcbname,,...) 



The CLOSE macro 

• is issued in the appUcation program to deactivate any open input or output data 
sets. 

CLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CLOSE 


(dcbname,,...) [MF=(l )] 
l(E,listname)j 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data control block(s) for the data set(s) 

being closed. 

Default: None. This operand is required. 

Format: Framing parentheses must be coded. Each dcbname must conform to 

the rules for assembler language symbols, and must be the same as the name of the 

DCB macro creating the control block. 

Notes: All application-program data sets can be closed with one CLOSE macro 

by including the names of their data control blocks as operands. 

If register notation is used, the register number must be enclosed in parentheses 
and addresses of the data control blocks must previously have been loaded into 
the registers specified. 

If more than one data set is being closed, the names must be separated by double 
commas. 



(IVIF= \ L 



I (E, listname) ) 



Function: Specifies Hst or execute form of the macro. 
Notes: See the OS publication, Supervisor and Data Management Macro 
Instructions^ for the definition and use of this operand. System ABEND 
issues CLOSE macros for all opened DCBs within a task when it abends. 



< 



380 OS/MFT and OS/MVT TCAM Programmer's Guide 



MCPCLOSE 



The MCPCLOSE macro 

• initiates closedown of the telecommunications system; 

• is optional in an appUcation program. 

MCPCLOSE may be issued in an application program to initiate system close- 
down. At the time MCPCLOSE is issued in a user-written termination routine, all 
data sets in the application program should be closed (if MCPCLOSE detects an 
open data set in any appUcation program, it issues a WTO message and places the 
MCP in a wait state until all data sets are closed). Following successful execution 
of MCPCLOSE, control passes to a user-specified routine that deactivates the 
MCP. For more information on the use of MCPCLOSE, see Deactivation in the 
chapter Activating and Deactivating the Message Control Program . 

Only one MCPCLOSE macro is needed to close down the entire system. The 
closedown functions of the macro are also available through use of the HALT 
operator command. 

One of the following codes is returned to the application program in register 1 5 
after the MCPCLOSE macro is issued: 



Code Meaning 

X'OOOOOOOO' The MCPCLOSE macro executed successfully. 
X'OOOOOOOC TCAM is not in the system. 
X'00000014' Either 

a) an invalid protection password is specified in the PASSWRD= 
operand, or 

b) the PASSWRD= operand is not specified and is needed 
because the INTRO macro's PASSWRD= operand specifies a 
protection password. 

MCPCLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


MCPCLOSE 


4 QUICK )[,PASSWRD=chars] 
(FLUSH j 



symbol 



(quick ) 

^FLUSHj 



\ 



Function: Specifies the name of the macro instruction. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the type of closedown required. 

Default: FLUSH 

Format: QUICK or FLUSH. 

Notes: QUICK specifies that message traffic is to cease upon completion of any 

message currently in progress. Messages queued for the destinations are not 

transmitted. 



Writing TCAM-Compatible Application Programs 38 1 



PASSWRD=chars 



FLUSH specifies that input message traffic is to cease upon completion of the 
message currently in progress. All messages queued for the destinations are then 
transmitted. 

Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand is specified on the INTRO macro in 
the MCP, this operand is required. Otherwise, specification optional. 
Format: One to eight unframed, nonblank characters. 
Notes: If the character string specified in this operand does not match that 
specified in the INTRO macro, the MCPCLOSE macro is ignored and a X*14' 
return code is set in register 15. 

Transferring Data Between an MCP and an Application Program 

TCAM provides the apphcation-program user with facilities for obtaining mes- 
sages from the MCP and for returning response messages to the MCP. 

The TCAM application programmer uses data-transfer macros similar to those of 
the Queued Sequential Access Method (GET and PUT) or the Basic Sequential 
Access Method (READ, WRITE, and CHECK) of OS/360. A TCAM Message 
Control Program performs device-dependent input/output operations for the 
apphcation program. 

Since the macros used by TCAM for transfer of data between an apphcation 
program and an MCP are patterned after those of BSAM and QSAM, the TCAM 
application programmer is expected to be famihar with these access methods, 
which are explained in the Supervisor Services, Data Management Services , and 
Supervisor and Data Management Macro Instructions publications. 

The amount of data transferred from the MCP to an application program by a 
single GET or READ macro, or transferred from an application program to the 
MCP by a single PUT or WRITE macro, is called a work unit . The work unit is 
processed in an appHcation-program work area . A work unit may be an entire 
message, or a portion of a message (which may or may not be a record). A 
message is a unit of data received from or sent to a station and terminated by an 
EOT or ETX line-control character, or, if the CONV= operand of the 
STARTMH macro is coded CONV=YES, by an ETX or EOB line-control 
character. (Line-control characters may be deleted by the MCP, but TCAM 
places the length of each message segment in the buffer prefix for that segment, 
and can determine the message length by adding the contents of the prefix fields.) 

A record is a logical unit of data whose length is defined by operands of the input 
or output DCB macro and delimiting characters in the message. In TCAM, each 
record is transferred to and from a remote station as part of a message, but the 
size of the record need not coincide with the size of the message; one message 
may contain many records. After an incoming message is placed on a process 
queue for the application program, the user obtains the records in it one at a time, 
with one record being passed between the MCP and the apphcation-program for 
each GET or READ macro directed to the process queue. Similarly, a record may 
be sent to the MCP from a work area whenever a PUT or WRITE macro naming 
the work area is issued in the application program. 

Just because a work unit is not an entire message does not mean that it is a record. 
Message processing or record processing is indicated by the OPTCD= operand of 



382 OS/MFT and OS/MVT TCAM Programmer's Guide 



i 



the input and output DCB macros. If message processing is specified, but the 
entire message does not fit into the work area, TCAM provides the capabiUty of 
processing a portion of the message in the work area, then bringing in the next 
portion and processing it, until the entire message has been processed. The 
portions of the message processed in this way are not considered to be records, 
since message processing rather than record processing was specified. TCAM 
handles records and other message portions differently, as shown below in the 
discussion of work units and work areas. These differences may be summarized as 
follows: 

• An incoming record cannot overflow the work area, whereas an incoming 
message can. 

• An incoming record may be delimited by a delimiting character specified by the 
RECDEL= operand of the TPROCESS macro; when message processing is 
specified in the input DCB macro, such delimiters are ignored. 

• If neither a delimiting character nor end-of-message is encountered in a record 
by the time the work area is full, the size of the record is assumed to be the size 
of the work area. When message processing is specified, a work-area overflow 
condition is assumed to exist if the work area fills before the entire message is 
read in; in this case, the user specifies, by an input DCB operand, whether he 
wants to process the message piece by piece or go to an error routine. 

• If a delimiting character is specified by the RECDEL= operand of the 
TPROCESS macro named in a PUT or WRITE macro, TCAM places 
the character at the end of each outgoing record. If message processing 
is specified, TCAM places no delimiting character at the end of outgoing 
messages or pieces of messages. 

The next three sections of this chapter discuss in detail the appHcation-program 
work-area, work-unit, and data-transfer macros. 

Defining the Application-Program Work Area 

Work units obtained by a GET or READ macro are transferred from the MCP to 
a work area defined by the user when he codes his application program. The 
work areas for TCAM-compatible application programs are similar to those for 
programs using the Basic or Queued Sequential Access Method. 



Static Work- Area Definition 



A work area may be defined in one of two ways. It may be defined at application- 
program assembly time by a DC or DS assembler instruction issued in the applica- 
tion program. The label of the instruction becomes the name of the work area, 
and is coded in the GET, PUT, READ, or WRITE instructions that move data to 
and from the work area. The size of the work area must be specified in the 
BLKSIZE= operand of the input DCB macro associated with the data set whose 
contents are being transferred to or from the work area. 

When a work area is defined in this way, move processing mode should be speci- 
fied by coding M in the MACRF= operand of the DCB macros referred to by the 
data-transfer macros that use the work area. A static work area may be used to 
receive data from or send data to more than one input or output data set. 



Dynamic Work- Area Definition 



r 



A work area may be defined dynamically at application-program execution time, if 
GET or PUT macros are to gain access to it. If the user specifies locate mode by 
coding L in the MACRF= operand of his input DCB macro, execution of the first 
GET macro referring to the opened data set causes TCAM to dynamically obtain 
a work area (by a GETMAIN macro) in the same area of addressability as the 



Writing TCAM-Compatible Application Programs 383 



application program, and to move a work unit of data into this work area. The 
length of the work area is that specified by the BUFSIZE= operand of the input 
DCB macro referred to by the GET macro. The address of the work area is 
returned in register 1 , and is saved by TCAM. The second and subsequent 
executions of GET macros referring to the DCB move data into this work area. 

If locate mode is specified by coding L in the MACRF= operand of the output 
DCB macro, execution of the first PUT macro referring to the opened data set 
causes TCAM to dynamically obtain a work area (by a GETMAIN macro) in the 
same area of addressability as the application program. The address of this work 
area is returned in register 1 . This address should be saved by the user and placed 
in work-area-address register before each PUT after the first is issued. The length 
of this work area is specified by the BLKSIZE= operand of the output DCB 
referred to by the PUT macro. The user must move his data into the work area 
before executing another PUT referring to this DCB. Execution of subsequent 
PUT macros referring to this DCB moves the data from this same work area into 
the MCP buffers. 

Moving Data between Input and Output Work Areas 

In some user appHcations, a work unit is transferred from the MCP to the appHca- 
tion program by a GET or READ, processed by the application program, and then 
returned to the MCP by a PUT or WRITE. If move mode is specified in the input 
and output DCB macros for the input and output data sets through which the 
work unit proceeds, then the GET/READ and PUT/WRITE macros may refer to 
the same work area; the user need not move his data from an input to an output 
work area. 

If locate mode is specified in the input or output DCB macro, and move mode is f] 

specified in the DCB macro for the other data set through which the work unit 'i 

passes, then the user can still get by with one work area, because TCAM permits 
specification of a register containing the address of the work area when GET or 
PUT is coded. 

If locate mode is specified for both the input and the output DCB macro, then two 
work areas will be present, and the work unit must be transferred from one to the 
other. 

Defining Optional Fields in the Work Area 

The following operands of the input and output DCB macros cause TCAM to 
create optional fields in the front part of the work area and fill them with data 
(input DCB macro) or to examine these fields (output DCB macro): 

. OPTCD=W 
. OPTCD=C 
. RECFM=V[B] 

If none of these operands are coded, TCAM starts with the first byte of the work 
area when filling or emptying it. 

The contents of the optional fields are not moved out of the work area with the 
message or record being processed. 

Origin and Destination Fields: If W is coded in the OPTCD= operand of the DCB 
macro of the input data set for this work unit, eight bytes of the work area are 
reserved for the name of the source of the message. When the message comes m 

into the work area, TCAM places the EBCDIC name of the source (as specified in ^ 



384 OS/MFT and OS/MVT TCAM Programmer's Guide 



> 



the terminal table) into these eight bytes. The name is left-adjusted, and the field 
is padded to the right with blanks if the name is shorter than eight bytes. 

If TCAM cannot determine the origin of a message, the field is filled in with eight, 
character blanks. TCAM usually knows the origin of a message. TCAM does not 
know the origin when a switched station with no ID sequence calls in and fails to 
identify itself by having a valid origin field in the message header checked by an 
ORIGIN macro. If the switched station is assigned an ID sequence that is not 
unique, an incorrect name may be placed in the field. (See the discussion of the 
ORIGIN macro for more information on switched stations with no ID sequences 
or shared ID sequences.) 

The eight-byte origin field immediately precedes the work unit in the work area 
and follows the other two optional fields, if either or both of the other fields are 
present. Figure 29 shows where the origin field goes in the work area. 

If W is coded in the OPTCD= operand of the DCB macro of the output data set 
for this work unit, when a PUT or WRITE macro is issued to move a work unit 
from this work area to the MCP, TCAM looks in an eight-byte field in the work 
area for the name of the destination of the message. The name should be in 
EBCDIC, left- justified, and padded to the right with blanks if necessary. If a 
FORWARD macro with the DEST= operand coded DEST=PUT is executed in 
the inheader subgroup of the Message Handler for an application program, the 
message is sent to the destination specified in the eight-byte field (see the descrip- 
tion of the FORWARD macro). 

TCAM assumes that the eight-byte destination field immediately precedes the 
work unit in the work area (if W is coded in the OPTCD= operand); Figure 29 
shows where TCAM looks for the destination field. Only the work unit, and not 
the contents of the destination field, is transferred to the MCP when a PUT or 
WRITE macro is executed. 

The user with an inquiry-response application may wish to refer to the same work 
area with his GET/READ and PUT/WRITE macros. If he codes W in the 
OPTCD= operands of his input and output DCB macros, TCAM places the origin 
in the eight-byte field when the inquiry message is read into the work area. After 
the application program processes the message data (without changing the con- 
tents of the eight-byte field), a PUT or WRITE macro is issued; the contents of 
the eight-byte field are now assumed to specify the destination. If a FORWARD 
macro with the DEST= operand coded DEST=PUT is coded in the inheader 
subgroup for the application program, the response message will go back to the 
originating terminal. 

Position Field: If C is coded in the OPTCD= operand of an input or output DCB 
macro, a one-byte field is reserved in the work area associated with the DCB (if 
locate mode is specified in the DCB macro) or named by the GET/READ or 
PUT/WRITE macro transferring data to or from an input or output data set. This 
position field is useful when messages sent to the application program are larger 
than the application-program work area that is to receive them (for example, when 
logical records or other message portions, rather than entire messages, are pro- 
cessed by the application programs). 

If C is specified in the OPTCD= operand of the input DCB macro containing the 
work unit to be moved into the work area. TCAM fills in the position field with a 



Writing TCAM-Compatible Application Programs 385 



code indicating whether this work unit is the first, intermediate, or last portion of 
a message, or an entire message. 

( 
If C is specified in the OPTCD= operand of the output DCB macro for the work 
unit, the application programmer must ensure that the position field contains the 
appropriate code to describe his work unit. TCAM checks this field and uses it to 
account for message portions being transferred to the MCP. The user must not 
interleave segments from different messages. If the operand is omitted from the 
output DCB macro, TCAM must make one of two assumptions, depending upon 
whether record processing or message processing is specified in the OPTCD= 
operand of the output DCB macro (message processing and record processing are 
described in the next section). 

• If message processing is specified, the end of the work unit is assumed to be the 
endof the message — that is, TCAM assumes that one work unit equals one 
message. 

• If record processing is specified, TCAM assumes that all work units being sent 
to the process entry associated with this output DCB, from the time the output 
data set is opened until the time it is closed, are part of the same message — that 
is, the application program signals end-of-message by issuing a CLOSE macro 
after the last work unit in the message is sent to the MCP. 

The position field is located in the work area, immediately to the left of the 
eight-byte origin or destination field. If no origin or destination field is present, 
the position field is located immediately to the left of the first byte of message 
data in the work area. Figure 29 shows the location of the position field in the 
work area. 

SAM Prefix: If V or VB is coded in the RECFM= operand of the input or output ,, 

/I 
DCB macro, a prefix field is assumed to be present in the work area containing the u 

message received from or sent to the data set represented by the DCB. This 

prefix is useful when TCAM/SAM compatibility — the abihty to run application 

programs in a non-teleprocessing environment using SAM data sets, and then run 

the same program in a TCAM environment without reassembUng — is desired (see 

TCAM/SAM Compatibility in this chapter). TCAM requires a SAM prefix when 

variable -format work units are specified in the output DCB macro (such work 

units are discussed in Work-Unit Formats in this chapter). 

The SAM prefix, if present, occupies the first four or eight bytes of the work area, 
as shown in Figure 29. 

If RECFM= V is coded in the input DCB macro, TCAM places a four-byte prefix 
into the work area receiving a work unit from the input data set for which the 
DCB macro was coded. The first two bytes of the prefix contain the binary sum 
of the length of the work unit plus four bytes (the length of the prefix). The 
second two bytes of the prefix each contain binary zeros. 

If RECFM=VB is coded in the input DCB macro, TCAM places an eight-byte 
prefix into the work area receiving a work unit from the input data set for which 
the DCB macro was coded, provided MACRF=R was also coded (a four-byte 
prefix is provided otherwise). The first two bytes of the prefix contain the binary 
sum of the length of the work unit plus eight bytes (the length of the prefix) in 
hexadecimal notation. The second two bytes each contain a binary zero. The 
third two bytes contain a binary number four less than that contained in the first 
two bytes. The final two bytes each contain a binary zero. This eight-byte prefix 
is for BSAM compatibility; work units are treated as if they were blocked records. 



< 



386 OS/MFT and OS/MVT TCAM Programmer's Guide 



although only one work unit is transferred for each READ or GET macro execu- 
tion. 

If RECFM=V is coded in the output DCB macro, TCAM assumes that a four- 
byte prefix precedes each work unit being sent to the output data set for which the 
DCB macro is coded. This prefix is similar to a standard SAM variable-length 
prefix; its contents are described above in the discussion of the SAM prefix for the 
input side. It is the application programmer's responsibihty to see that the prefix 
contains the proper data before a PUT or a WRITE is issued. 

If RECFM=VB is coded in the output DCB macro, TCAM assumes that the work 
unit being sent to the output data set for which the DCB macro is coded is preced- 
ed by an eight-byte prefix (provided that MACRF=W is also specified; a four- 
byte prefix is provided otherwise); the layout is the same as that described above 
for the eight-byte BSAM-compatible prefix for the input side. This prefix is for 
BSAM compatibility; work units are treated as if they were blocked, although only 
one work unit is transferred for each WRITE macro. It is the application 
programmer's responsibility to see that the prefix contains the proper data before 
a WRITE macro is executed. 

Specifying Application-Program Work Units 

The way in which TCAM decides how long a work unit is and how to handle it 
depends upon two factors: 

• the format of the work unit (fixed, variable, or undefined); 

• the type of work unit (message or record). 

The user specifies the format and type of work units his application program is to 
process by coding operands of the input and output DCB macros for the applica- 
tion program. These operands indicate whether the work unit is a message or a 
record, and whether it is always the same length or may vary in length from 
message to message or from record to record. 

If messages or records sent to an application program may vary in length, user 
code in the application program will need to be given length of the work unit 
currently being processed. TCAM counts the number of bytes in the incoming 
work unit, adds the number of bytes that must be reserved in the work area for 
optional fields, and places the total either in a special field in the work area or in a 
field in the input DCB (depending upon which field the user specifies in an input 
DCB operand). User code may then inspect this field to determine the length of 
the work unit being processed. 



4 bytes 



1 byl-e 



8 byfes- 



SAM Prefix 



Pos. 
Field 



Origin or DesHnation Field 



Start of 
Work Area 



Start of 
Work Unit 



Figure 29. Relative Positions of Optional Fields in the Work Area 



Writing TCAM-Compatible Application Programs 387 



Work-Unit Formats 



On the output side of the appUcation program, TCAM must know the length of 
messages or records whose lengths may vary, before these work units can be 
transferred to the MCP. The application programmer must ensure that the sum of 
the work-unit length and the length of any optional fields in the work area has 
been placed in a special field in the work area or output DCB before issuing a 
PUT or WRITE macro to transfer the work unit. 

The next two sections of this chapter discuss the effects of work-unit format and 
type upon the way in which TCAM transfers the work unit to and from the 
application program. Figure 30, at the end of the second section, summarizes 
much of this discussion. 



Work units that always have the same length are said to have a fixed format, while 
work units that may vary in length may have either a variable format or an unde- 
fined format, depending upon the location of the field in which their length is 
stored (for incoming work units) or examined (for outgoing work units) by 
TCAM. 

A fixed-format work unit is one whose length is defined by the number of bytes 
coded in the LRECL= operand of the input and output DCB macros. A 
variable-format work unit is one whose length (plus the length of any optional 
fields in the work area) is stored in the SAM prefix in the work area (see SAM 
Prefix in this chapter). An undefined-format work unit is one whose length (plus 
the length of any optional fields in the work area) is stored in a field in the input 
or output DCB. TCAM counts the number of bytes in the incoming work unit for 
both variable- and undefined-format work units — ^the only difference between the 
two types of work units (other than the lengths of their respective prefixes) is the 
location of the field where the count is stored by TCAM. 

The user specifies the kind of work units his application program expects to accept 
by the RECFM= operand of the input DCB macro. If he codes RECFM=F, then 
TCAM knows that this appHcation program is set up to process fixed-length work 
units and looks for the length of these units in the LRECL field of the input DCB. 
If he codes RECFM=V, then TCAM keeps track of the length of each incoming 
work unit and stores, in the SAM prefix, the sum of this length plus the length of 
any optional fields in the work area If he codes RECFM=U, then TCAM keeps 
track of the length of each incoming work unit and stores the sum of this length 
plus the length of any optional fields in the work area in the LRECL field in the 
input DCB. 

For work units being transferred from an application program to the MCP, a 
similar setup prevails. The user tells TCAM, by the RECFM= operand of the 
output DCB macro, where to look for the length of the work unit being sent back 
to the MCP by each PUT or WRITE macro. If the user specified RECFM=F, 
TCAM looks for the length of the work unit in the LRECL field of the output 
DCB. If the user specifies RECFM=V, TCAM looks for the sum of the length of 
the work unit plus the length of any optional fields in the work area in the length 
field of the SAM prefix in the work area. If the user specifies RECFM=U, 
TCAM looks for the sum of the length of the work unit plus the length of any 
optional fields in the work area in the LRECL field of the output DCB if a PUT or 
WRITE is being issued. It is up to the user to ensure that the field TCAM exam- 
ines contains the correct length; the technique for modifying a DCB field is 
described in Data Management Services . If the WRITE macro is used with the 
length operand, the length specified in the WRITE macro is used. 



4 



i 



388 OS/MFT and OS/MVT TCAM Programmer's Guide 



The tables below summarize the TCAM work-unit formats and illustrate how they 
are specified by operands of the input and output DCB macros. 

The delimiter mentioned in the discussions of variable and undefined records is 
the end of the message when message processing is specified; for record process- 
ing, the delimiter may be either the end of the message or a special record- 
dehmiting character specified in by the RECDEL= operand of the TPROCESS 
macro creating the queue used by the GET or READ. 
Work-Unit Formats — Input DCB 



Format 


How Specified 


Significance 


Fixed 
Variable 

Undefined 


RECFM=F 
RECFM=V[B] 

RECFM=U 


All incoming work units (except possibly the 
last in a message) are the same length. When a 
GET or READ macro is executed, TCAM at- 
tempts to bring in the number of bytes specified 
by the LRECL= operand of the input DCB 
macro. 

Incoming work units vary in length. When a 
GET or READ macro is executed, TCAM 
brings in data until a delimiter or the end of the 
work area is encountered, and then places the 
sum of the length of the work unit plus the 
length of any optional fields in the work area in 
the SAM prefix, which precedes the work unit 
in the work area. 

Incoming work units vary in length. When a 
GET or READ macro is executed, TCAM 
brings in data until a delimiter or the end of the 
work area is encountered, and then places in the 
LRECL field in the input DCB the sum of the 
length of the work unit plus the length of any 
optional fields in the work area. 



Writing TCAM-Compatible Application Programs 389 



Work-Unit Formats — Output DCB 



Format 



How Specified 



Significance 



Fixed 



RECFM=F 



Variable 



RECFM=V[B] 



Undefined 



RECFM=U 



A PUT or WRITE macro referring to this DCB 
moves the number of bytes specified in the 
LRECL field of this DCB from the work area 
to the MCP. TCAM subtracts the length of any 
optional fields from the number specified in the 
LRECL fiield. 

When a PUT or WRITE macro referring to this 
DCB is executed, TCAM determines the length 
of the work unit to be moved by looking in the 
SAM prefix preceding the work unit in the work 
area (and subtracting the length of any optional 
fields in the work area). 

If a PUT macro referring to this DCB is execut- 
ed, TCAM determines the length of the work 
unit to be moved to the MCP by looking in the 
LRECL field of the DCB. If a WRITE macro 
with the 'S' operand referring to this DCB is 
executed, TCAM determines the length of the 
work unit to be moved by looking in the 
LRECL field of the DCB. (In either case, 
TCAM subtracts the length of any optional 
fields in the work area from the value found.) 
If the WRITE macro with the length operand 
referring to this DCB is executed, TCAM uses 
the length specified in the WRITE macro as the 
length of the work unit to be moved. 



Work Unit Types 



An application program may be set up to handle messages or records. A work unit 
may be a message or a portion of a message; a work unit that is a portion of a 
message may be, but need not be, a record. 

The terms message and record are defined above, in the section Transferring 
Data Between an MCP and an Application Program ; differences in the manner 
in which TCAM handles records and the manner in which it handles other mes- 
sage portions that are not records are also summarized under this heading. The 
table at the end of this section gives a more detailed contrast between message 
and record processing by TCAM. 

The user specifies that he has set up his application program to handle messages 
by coding U in the OPTCD= operand of the input DCB macro. If U is not coded, 
TCAM assumes that the incoming work unit is a record. 

Processing the Message as a Work Unit: If U is coded in the OPTCD= operand of 
the input DCB macro, TCAM attempts to read in an entire message when a GET 
or a READ macro is executed. If the work area is large enough to accommodate 
the entire message, TCAM reads in data up to and including the EOT or ETX 
line-control character, unless conversational mode is specified in the STARTMH 



i 



390 OS/MFT and OS/MVT TCAM Programmer's Guide 



I 



macro, in which case TCAM reads in a block of data (that is, that amount of data 
deHmited by an EOB or ETB character when received by the computer). If 
LC=OUT is specified in the STARTMH macro associated with the Hne group 
DCB macro, the EOB or ETB line-control character is removed when the message 
comes into the incoming group of the MCP, but the EOT or ETX line-control 
character is not removed. 

If the entire message does not fit into the designated work area, TCAM performs 
one of three actions, depending upon how operands of the input DCB macro are 
coded. 

1. If a position field is specified in the OPTCD= operand, the portion of the 
message that did not fit into the work unit is obtained by the next GET or 
READ macro executed (the position field is discussed in Optional Fields in 
the Work Area in this chapter). 

2. If no position field is specified but SYNAD= is coded, TCAM gives control to 
the routine specified by SYNAD= (this routine is discussed in 
Application-Program Error- Handling Facilities in this chapter). 

3. If neither a position field nor a SYNAD exit is specified, TCAM places a return 
code of X'00000008' in register 15. This return code indicates an error condi- 
tion, and the user should terminate the application program and correct the 
error. 

If TCAM performs the first of these three actions, the application program may 
process the first portion of the message and issue a PUT or WRITE macro to 
return it to the MCP before issuing a GET or READ to bring in the rest of the 
message. 

To determine whether an incoming message fits into the work area, TCAM must 
first know what the length of the work area is. For fixed-format messages, TCAM 
assumes that the length of the work area is equal to the number of bytes specified 
in the LRECL= operand of the input DCB macro. For variable- and undefined- 
format messages, TCAM assumes that the work-area length is equal to the 
number of bytes specified in the BLKSIZE= operand of the input DCB macro. 
When a work-area overflow error occurs, TCAM discards the message that caused 
the overflow. If the input data set is closed and then reopened as a result of 
work-area overflow, the first message received in the work area following reopen- 
ing of the data set is not the message that caused the overflow; this message is 
discarded by TCAM. 

To prevent work-area overflow, the CUTOFF macro can be coded in the inbuffer 
subgroup of the MH; this macro checks the length of incoming messages and 
permits cancellation of messages that would be too long for the work area. 

If U is specified in the OPTCD= operand of the output DCB macro, TCAM 
assumes message processing on the output side. If a position field is specified in 
the work area (by coding OPTCD=C in the output DCB macro), TCAM uses this 
field to determine whether the work area contains an entire message or only a 
portion of a message. If the work area does not contain an entire message, TCAM 
treats each piece of data moved from the work area by a PUT or WRITE as part 
of the same message, until the contents of the position field indicate that the work 
unit currently being processed is the last unit in the message. If no position field is 
specified, TCAM assumes that the entire message is located in the work area. 

Depending upon the format of the work unit (whether it is fixed, variable, or 
undefined), TCAM looks in the SAM prefix or in an output DCB field for the 



Writing TCAM-Compatible Application Programs 391 



length of the outgoing work unit and sends out the quantity of data specified in 
the appropriate field, after allowing for optional fields in the work area. (See 
Work-Unit Formats in this chapter for information on the exact location of the (; 

field containing the message length.) ^ 

Processing the Record as a Work Unit: If U is not coded in the OPTCD= operand 
of the input DCB macro, TCAM treats the incoming work unit as a record, rather 
than as a message or a message portion that is not a record. 

If the user specifies that the input to his appUcation program is to be fixed-format 
records (by coding RECFM=F in the input DCB macro), TCAM assumes that 
each incoming record is equal in length to the number of bytes specified in the 
LRECL= operand of the input DCB macro (minus the length of any optional 
fields in the work area) and moves in this number of bytes each time that a GET 
or READ macro is executed for this input data set. The last record in a message 
may be shorter than the number of bytes specified by LRECL=, in which case 
TCAM brings in the actual number of bytes in this record. 

If fixed-format records are designated as the output from an application program 
(by coding RECFM=F in the output DCB macro), each time a PUT or WRITE is 
executed TCAM transfers to the MCP a record equal in length to the number of 
bytes specified in the LRECL= operand of the output DCB macro (after making 
allowance for the length of optional fields in the work area). 

If the user specifies that the input to his application program is to be variable- or 

undefined-length records (by coding V or U, respectively, in his input DCB 

macro), TCAM determines the length of incoming records according to the 

following principles: 4 

1. If a delimiting character (specified by the RECDEL= operand of the % 
TPROCESS macro creating the destination queue used by the GET or READ 
macro) is encountered while the work area is being filled, TCAM assumes that 

the current record ends with this character. The user may request that delimit- 
ing characters be removed from the data by specifying DELETE = YES on the 
TPDATE macro. 

2. If the end of a message is reached before the work area is filled, TCAM as- 
sumes that the last character in the message is also the last character in the 
current record. 

3. If neither a delimiter nor the end of the message is reached by the time the 
work area is filled, TCAM assumes that the length of the record is equal to the 
size of the work area (minus the size of any optional fields in the work area). 
TCAM determines the size of the work area by looking in the BLKSIZE field 
of the input DCB. 

When record processing is specified in the DCB macro for the output data set, 
TCAM sends out a single record with each PUT or WRITE. The size of the 
record is indicated in the SAM prefix for variable-format records, in the LRECL 
field of the output DCB, or in the WRITE macro for undefined-format records 
transferred by a PUT or WRITE. 

The following table and Figure 30 summarize many points discussed in this 
section and in the one immediately preceding it. 



( 



392 OS/MFT and OS/MVT TCAM Programmer s Guide 



Differences between Message and Record Processing: 



Message Processing 



Record Processing 



On Input: • When GET/READ is issued, 
TCAM brings in data until 
either the end of the 
message is encountered or 
the work area is filled. 



• If the work area has been 
filled and the end of the 
message was not reached, 
TCAM either brings in the 
rest of the message with 
the next GET or READ (if 
a position field is present 
in the work area), or goes to 
the error-handhng routine 
specified by the SYNAD= 
operand of the input DCB 
macro. 

On Output: • Whenever PUT/WRITE is 
executed, TCAM transfers 
one work unit of data from 
the application-program work 
area to the MCP. 



. When GET/READ is 
issued, TCAM brings in 
data until 1 ) the 
delimiting character 
specified by the 
TPROCESS macro referred 
to by the GET or READ 
is encountered, or 2) 
the end of the message 
is encountered, or 3) 
the work area is filled. 
(Delimiting character is 
ignored for fixed-format 
records.) 

• If the work area is 
filled, TCAM assumes 
that a complete record 
has been received. 



• Same as for messages 
— one work unit (record) 
transferred per PUT or 
WRITE. 



• The RECDEL= operand of the 
output TPROCESS macro is 
ignored. 



• The delimiting character 
specified by the RECDEL= 
operand of the output 
TPROCESS is placed at the 
end of each outgoing 
undefined-format record and 
each outgoing variable-format 
record, except for the last 
record of the message. 



I 



• If a position field is pre- 
sent and indicates an initial or 
intermediate segment, TCAM trans- 
fers the rest of the message to 
the MCP when the next PUT or 
WRITE is executed for this out- 
put data set. If no position 



• If a position field 
is present, TCAM con- 
siders all records to be 
part of the same message 
until the position field 
indicates that the cur- 
ent record is the last 



Writing TCAM-Compatible Application Programs 393 



field is present, TCAM assumes 
that the end of the message coin- 
cides with the end of the work 
area. 



record in the message. 
If no position field is 
present, execution of 
the CLOSE macro for the 
output data set signals 
the end of the message. 



Signaling End of File and End of Message 

TCAM can signal the apphcation program that the contents of the message 
currently being processed by the apphcation program constitute the end of a 
logical file of data; after processing the work unit, or units, in this message, the 
apphcation program may take an exit to a user-defined, end-of-data subroutine. 
Such a subroutine might close the input data set, cause a different type of 
appHcation-program activity to begin, issue a GET or READ macro referring to a 
different process queue, etc. 



The user indicates that the contents of the current message represent the final 
portion of a logical file of data by issuing a SETEOF macro in the outheader 
subgroup of the application-program Message Handler. SETEOF can be coded to 
execute conditionally based on the presence of a specified character string in the 
message header. When SETEOF executes, a bit is set in the prefix of the mes- 



Work-Unif Type: 


Record 


Message 


Work-Unit Format: 


Fixed 


Variable 


Undefined 


Fixed 


Variable 


Undefined 


Input Side 
(GET/READ) 


Work-Unit 

Size 
Determined 

By: 


LRECL field 

of 
input DCB 


X 






X 






BLKSiZE field 

of 
input DCB 




X 


X 




X 


X 


length field 

of 
READ macro 






X 






X 


delimiter 
specified via 
TPROCESS macro 




X 


X 








end -of -message 


X 


X 


X 


X 


X 


X 


Work-Unit 

Size 
Stored In: 


field in SAM 
prefix 




X 






X 




LRECL field 

of 
input DCB 






X 






X 


Output Side 
(PUT/WRITE) 


Work-Unit 

Size 
Determined 

By: 


LRECL field 

of 
output DCB 


X 




X 


X 




X 


length field 

of 
WRITE macro 






X 






X 


field in SAM 
prefix 




X 






X 




Delimiter Specified via TPROCESS Macro 
Inserted After Each Record 




X 


X 









< 



Figure 30. Effect of Work-Unit Type and Format on the Way in which TCAM Determines its Size 



394 OS/MFT and OS/MVT TCAM Programmer's Guide 



sage, indicating that this is the last message in the file. When a message with this 
bit on in the prefix is transferred to the appHcation program by GET or READ 
macros, TCAM notes and remembers that this is the last message in the file. 
Execution of the first GET or CHECK macro following transfer of the entire 
end-of-file message to the application-program work area gives control to the 
subroutine specified by EODAD. 

Upon entry to the user-specified subroutine, the registers contain the same data as 
before execution of the GET or CHECK macro, except that register 15 contains 
the address of the exit subroutine. 

If the user returns from this subroutine to the subroutine issuing GET or READ 
macros, these macros will execute in a normal fashion. 

If no SETEOF macro is executed and a GET or READ macro referring to an 
empty process queue is issued, the application program enters a wait state until a 
message arrives at the process queue for the appUcation program. (If READ was 
issued, the wait state begins only when the CHECK macro is executed.) 

If the SETEOF macro executes and no EODAD exit is specified, when the next 
GET or CHECK macro following transfer of the entire end-of-file message to the 
application program is executed, a completion code of X'00000004' is returned by 
TCAM in register 15, and control returns to the application program. User code 
may check for this return code and take appropriate action. 

If record processing is specified (by the absence of U in the OPTCD= operand of 
the output DCB macro), the user may indicate that this is the last record in a 
message being sent from the application program to the MCP by coding XT2' in 
the position field preceding the record in the work area (see Optional Fields in 
the Work Area in this chapter for a description of the position field). If no 
position field is defined, the program may signal TCAM that the last record in the 
message has been sent by closing the output data set after executing a PUT or 
WRITE macro for this last record. (If message processing is specified, and no 
position field is provided, TCAM assumes that the work unit being processed 
constitutes the entire message.) 

Coding TCAM Data Transfer Macros 

TCAM provides facilities for obtaining messages from the MCP for processing 
and for returning response messages to the MCP. Although the messages are 
received from (or sent to) remote stations over communication Unes, the program- 
mer uses QSAM (GET and PUT) or BSAM (READ, WRITE, and CHECK) 
macros for obtaining and sending messages. A TCAM Message Control Program 
performs the device-dependent input/output operations for the application 
program. The user specifies whether he wishes to use the GET/PUT or 
READ/WRITE/CHECK support in the MACRF= operand of the input and 
output DCB macro. 

Since TCAM GET/PUT and READ/WRITE/CHECK support is similar to that 
provided by OS, the TCAM application programmer is expected to be thoroughly 
familiar with the OS sequential access method (BSAM or QSAM) whose counter- 
part he is coding in the TCAM application program. This requirement implies a 
knowledge of the applicable contents of Data Management Services and 
Supervisor and Data Management Macro Instructions. 



Writing TCAM-Compatible Application Programs 395 



GET (QSAM only) 



symbol 



dcbname 



The GET macro 

• obtains work units from the MCP for processing; 

• may be coded more than once in an appHcation program. 

The GET macro transfers a single work unit from the MCP to an appHcation- 
program work area. The size of the work unit transferred depends upon whether 
record or message processing is specified by the OPTCD= operand of the input 
DCB macro ( Specifying Application-Program Work Units in this chapter details 
the differences between record and message processing). 

If a GET macro follows a POINT macro and the message cannot be retrieved, a 
code of X'OC is returned in register 15. If a GET macro is issued and the 
BLKSIZE value is zero, a code of X*10' is returned in register 15. 

If a GET macro is issued after a quick closedown of the MCP has begun, the 
EODAD exit is taken. 

GET has the following format: 



Name 


Operation 


Operands 


symbol 


GET 


dcbname[,areaname] 



Function: Specifies the name of the macro instruction. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the symbohc address of the data control block associated 
with the process queue from which the appHcation program is to obtain a work 
unit. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The DD statement for this DCB names a process entry in the terminal 
table; the process entry is coded especially to receive messages from the appHca- 
tion program. See Overview of the MCP / Application-Program Interface in this 
chapter. 

If register notation is used, the register number (2 through 12) must be enclosed in 
parentheses, and the address of the data control block must previously have been 
loaded into the register. 



Function: Specifies the symboHc address of the user-defined area into which the 
work unit is to be placed. 

Default: None. If move mode is specified in the MACRF= operand of the input 
DCB macro, this operand is required. Otherwise, specification optional. 
Format: Must conform to the rules for assembler language symbols. 



{ 



396 OS/MFT and OS/MVT TCAM Programmer's Guide 



Notes: If register notation is used, the specified register number must be enclosed 
in parentheses and the address of the work area must previously have been loaded 
into the register (1 through 12). 

This operand may be omitted if locate mode is specified in the input DCB macro, 
in which case TCAM obtains a work area from application-program main storage 
by issuing a GETMAIN macro instruction when the input data set is opened. 
After the first GET, TCAM returns the address of the work area in register 1. 
TCAM uses this same work area until termination. 



Writing TCAM-Compatible Application Programs 397 



PUT (QSAM only) 



symbol 



The PUT macro 

• returns work units to the MCP after processing; 

• may be specified more than once in an application program. 

The PUT macro causes the processed message or message segment to be trans- 
ferred from the work area specified to the MCP, where it is processed by the 
incoming group of the MH for the application program, and then placed on the 
destination queue for a particular destination. This destination may be specified 
either in the message header and subsequently checked by a FORWARD macro in 
the incoming group handling messages from an application program, or as an 
operand of the FORWARD macro, or in a special destination field in the work 
area that may be filled in by user code before the PUT is issued (see Defining 
Optional Fields in the Work Area in this chapter for a description of the desti- 
nation field). 

If a PUT is issued and the message queues data set, on reusable disk or in main 
storage, that contains the destination queue for the destination of the message is 
congested with traffic, the PUT does not execute, a code of X'OOOOOOIO' is 
returned in register 15, and control passes to the next instruction; in this case, the 
user may test the return code and re-issue the PUT. 

If a PUT macro is issued after a quick closedown of the MCP has begun the 
operation does not complete, a return code of X'04' is placed in register 15, and 
control passes to the next instruction. If the position field contains an invalid 
value or a value that is out of sequence with the previous position field, a code of 
X'08' is returned in register 15. If the destination name field contains a name that 
is not a valid entry in the terminal name table, X'OC is returned in register 15. 

PUT has the following format: 



Name 


Operation 


Operands 


[symbol] 


PUT 


dcbname[,areaname] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



dcbname 



Function: Specifies the symbolic address of the data control block for the output 
data set. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The DD statement for this DCB names a process entry in the terminal 
table; the process entry is coded especially to receive messages from the applica- 
tion program. See the Overview of the MCP /Application-Program Interface in 
this chapter. Do not try to execute a PUT or WRITE macro in an application 
program if there is a PUT or WRITE macro currently executing and indirectly 



i 



398 OS/MFT and OS/MVT TCAM Programmer's Guide 



I 





referring to (by the TPROCESS entry) the same process control block (PCB). 
This condition could occur if two subtasks of the same apphcation program with a 
single PCB tried to execute a PUT or WRITE macro. If for some reason the 
TCAM MCP must wait before the first operation can be completely processed, 
the second subtask of the same application program could gain control and try to 
execute a PUT or WRITE macro. As a rule, the MCP would be forced to wait 
only if there was a buffer shortage or if the message being processed was an 
operator control message that required a long time to process. 

To guard against this condition, TCAM returns an indication. If an attempt is 
made to execute a PUT macroj TCAM will return an error indication X'lO' in 
register 15. For a WRITE macro, the DECB will contain a completion code of 
X'SCOOOOOO'. Unlike other PUT/WRITE errors, the user is not required to close 
down the DCB affected. 

If more than one subtask in the same apphcation program includes PUT or 
WRITE macros, the possibihty of this type of error can be eliminated by use of 
the ENQ and DEQ macros. ENQ can be coded before each PUT or WRITE, and 
DEQ can be coded after each PUT or WRITE macro. The resource must be a 
name that symbohzes the PCB. See the Supervisor and Data Management 
Macro Instructions publication. 

If register notation is used, the register number specified must be enclosed in 
parentheses, and the address of the data control block must have been loaded 
pi-eviously into a register (1 through 12). 



Function: Specifies the symbohc address of the user-defined work area from 

which the work unit is to be transferred. 

Default: None. If move mode is specified in the MACRF= operand of the 

output DCB macro, this operand is required. Otherwise, specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the register number specified must be enclosed 

in parentheses and the address of the work area must previously have been loaded 

into a register (0, or 2 through 12). 

If locate mode is used, this operand should be omitted. In this case, the address of 
a work area into which the next work unit is to be placed is returned in register 1 
for the first PUT macro referring to this DCB. For more information on locate 
mode, see Dynamic Work Area Definition in this chapter. 



Writing TCAM-Compatible Apphcation Programs 399 



READ (BSAM only) 



The READ macro instruction causes a work unit to be moved from the MCP into 
a designated area of main storage in the application program. It differs from the 
GET macro in that control may be returned before the work unit is retrieved when 
READ is used, whereas with GET control is not returned to the application 
program until the work unit is in the work area. The READ input operation may 
be tested for completion using a CHECK macro instruction; once CHECK is 
issued, control is not returned to the appHcation program until the work unit is in 
the work area. 

An appHcation program containing more than one READ macro should be 
designed so that each data event control block (DECB) generated by a READ 
macro is associated with one and only one process queue from OPEN to CLOSE 
(that is, the decbname and dcbname operands of the READ macro, once speci- 
fied, should always be paired; decbname should not be specified with a particular 
dcbname in one READ macro and then associated with a different dcbname in 
another READ macro). The user may specify only one DECB per process queue. 
This technique allows the user to determine the status of any process queue by 
merely interrogating the current completion code in the DECB. See the comple- 
tion codes in the next section. (The DECB is a system control block; for informa- 
tion on the layout of this control block see the System Control Blocks publica- 
tion.) 

If a READ macro is issued after a quick closedown of the MCP has begun, the 
EODAD exit is taken. 

Since only one DECB may be specified per process entry, multiple READ macros 
directed to the same process queue are not permitted. However, the user may 
achieve the effect of issuing multiple READ macros directed to the same process 
queue by coding a hst and an execute form of the READ macro. This is achieved 
by coding one hst form of READ and several associated execute form READ 
macros, where the list READ and all the execute READ macros specify the same 
DECB. This technique does not provide a real multiple- wait facility, but allows 
the application programmer to code READ macros that refer to the same DECB 
in one or more sections of the same program. The list and the execute forms of 
the READ macro are explained in Supervisor and Data Management Macro 
Instructions . 

A DECB is posted with a X'40000000' when a message is placed on a previously 
empty read-ahead queue for a process entry. This implies that a DECB may be 
posted any time during the execution of an appHcation program after the first 
READ macro is issued foHowing OPEN. This differs from BSAM in that a DECB 
becomes eHgible for posting only after a READ macro is issued by the user. 
Therefore, under TCAM/BSAM, a READ DECB may already be posted com- 
plete when the user issues a READ, CHECK, or WAIT macro. 

Example: 

In the following example, two READ macros of the execute form and one READ 
macro of the list form are coded. AH three macros specify the same DECB 
(named INPUT); the Hst READ also specifies the appropriate DCB and work 
area. 



m 



400 OS/MFT and OS/MVT TCAM Programmer s Guide 



symbol 



decbname 



SF 



dcbname 



READ 
CHECK 



READ 
CHECK 



LIST 
IN ARE A 
INDCB 



User Code 

INPUT, SF,MF=(E, LIST) 
INPUT 

User Code 

INPUT, SF,MF=( E, LIST ) 
INPUT 

User Code 

Constant Area 

READ INPUT, SF, INDCB, INAREA,MF=L 
DC 50F'0' 

DCB DSORG=PS , MACRF=R, BLKSIZE=200 , 
OPTCD=WUC , RECFM=V , DDNAME=IN 



READ has the following format: 



Name 


Operation 


Operands 


[symbol] 


READ 


decbname,SF, 

dcbname,areaname, 

Uength? 

rs' ilMF^a n 

L KE,Ustname)y 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name to be assigned to the data event control block 

(DECB) created as part of the macro expansion. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Function: None. Must be coded for proper macro expansion. 
Default: None. This operand is required. 
Format: SF 



Function: Specifies the symbolic address of the data control block associated 

with the process queue being used. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the address of the data control block must 

previously have been loaded into a register (1 through 12), and the register 

number must be enclosed in parentheses. 

The DD statement for this DCB names a process entry, in the terminal table, 
coded especially to receive message from the appUcation program. 



Writing TCAM-Compatible Application Programs 401 



S length } 



IVIF=fL I 

I (E,nstiiame)| 



Function: Specifies the name of the work area into which the work unit is to be 

placed. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the address of the work area must previously 

have been loaded into a register (2 through 12), and the register number must be 

enclosed in parentheses. 



Function: Specifies the sum of the length of the work unit to be read plus the length 

of any optional fields in the work area. 

Default: *S' 

Format: length is an unframed decimal integer. 

Maximum: 32760 for length. 

Notes: This operand is coded only for undefined-format work units; it is ignored 

for fixed- and variable-format work units. 

Note that S is enclosed in single quotes. If 'S' is coded, and an undefined-format 
work unit is to be processed, the number of bytes to be read is taken from the 
LRECL= operand of the input DCB macro; for undefined-format work units, 'S' 
is the default. 



Function: Specifies the list or execute form of the macro. 

Notes: Described in Supervisor and Data Management Macro Instructions . 



i 



402 OS/M FT and OS/M VT TC AM Programmer's Guide 



WRITE (BSAM only) 



symbol 



decbname 



SF 



The WRITE macro 



• returns work units to the MCP after processing; 

• may be specified more than once in an appUcation program. 

The WRITE macro instruction causes the contents of a work area in the applica- 
tion program to be moved to the MCP in the same manner as PUT. Control may 
be returned before the block is moved. The output operation may be tested for 
completion using a CHECK macro instruction. (See the next section for a 
completion code table.) 

The destination may be specified either in the message header and subsequently 
checked by a FORWARD macro in the incoming group handling messages from 
an application program, or by an operand of the FORWARD macro, or in a 
special destination field in the work area that may be filled in by user code before 
the WRITE is issued (see Defining Optional Fields in the Work Area in this 
chapter for a description of the destination field). 

If a WRITE macro is issued after a quick closedown of the MCP has begun, the 
operation does not complete, and a completion code of X'5E' is placed in the 
DECB. 

WRITE has the following format: 



Name 


Operation 


Operands 


[symbol] 


WRITE 


decbname, SF, 
dcbname,areaname, 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name to be assigned to the DECB created as part of the 

macro expansion. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Function: None. This operand must be coded for proper macro expansion. 
Default: None. This operand is required. 



dcbname 



^ 
^ 



Function: Specifies the name of the data control block associated with the 

destination queue. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Writing TCAM-Compatible Application Programs 403 



{ length I 



Notes: If register notation is used, the specified register number must be enclosed 
in parentlieses and the address of the data control block must previously have 
been loaded into a register (1 through 12). 



Function: Specifies the address of the area from which the work unit will be 

moved to the MCP. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the specified register number must be enclosed 

in parentheses and the address of the work area must previously have been loaded 

into a register (2 through 12). 



Function: Specifies the sum of the length of the work unit to be transferred to the 

MCP plus the length of any optional fields in the work area. 

Default: ^ 

Format: length is an unframed decimal integer. 

Maximum: 32760 for length. 

Notes: This operand is meaningful only for undefined-format work units; it is 

ignored for fixed- or variable-format work units. Note that S is enclosed in single 

quotes. If 'S' is specified and and undefined-format work unit is specified, the 

number of bytes to be written is taken from the LRECL= parameter of the output 

DCB macro. 

BSAM/TCAM Completion Codes: After the user has issued a READ or WRITE, 
and the TCAM READ or WRITE routine has completed execution, a completion ,^ 

code is placed in the ECB in the DECB associated with the READ or WRITE. [^ 

The codes are: 

Hex Code Meaning 

7F000000 Normal completion. (READ and WRITE) 

70000000 SETEOF macro executed in MCP. The work area does not contain 

a work unit. (READ only) 
5C000000 Congested destination message queues data set (WRITE only) 
5E000000 TCAM quick closedown has begun. Request rejected. (WRITE 

only) 
58000000 Work unit sequence error. (WRITE only) 
54000000 Invalid message destination. (WRITE only) 
52000000 Work area overflow. (READ only). Also returned if DCB contains 

a BLKSIZE value of zero. 
50000000 READ issued in conjunction with a POINT macro to retrieve a 

message; message not found. 
40000000 Data on read-ahead queue. 
02000000 End of queue condition (not SETEOF and no data in TCAM MCP 

for DCB). 
01000000 Read-ahead queue empty, but destination queue not empty. 

The primary use of these codes is for communication between the READ or 
WRITE and CHECK routines (see the next section). If a user prefers to issue a 
WAIT macro rather than a CHECK macro, he is responsible for testing the 
completion code. A completion code of X'70000000' indicates an end-of-file £ 

condition and requires CHECK to take the user's EODAD exit. Code ^ 



404 OS/MFT and OS/MVT TCAM Programmer's Guide 



X'5E000000' indicates that the WRITE was not effective because a request for 
quick close-down is in effect. Code X'5C000()00' indicates that the WRITE was 
not effective because the message queues data set for the destination is congested 
with traffic and cannot accept the work unit at this time. The user may issue 
another WRITE in this case. Codes X^52000000', X^54000000\ and 
X'58000000' indicate error conditions and require CHECK to take the user's 
SYNAD exit. Completion code X'58000000' indicates that the output DCB 
macro associated with the WRITE macro specifies OPTCD=C and that the 
work-unit position field specifies the wrong type of work unit — for example, the 
position field might indicate that this work unit is the first portion of a message, 
but the position field for the previous work unit processed did not indicate that it 
was the last portion of a message. Codes X'02000000' and X'0 1000000' indicate 
that the process queue has no data on it; when data is placed on the queue, the 
code is automatically changed from X'02000000' to X'40000000\ Code 
X'40000000' indicates that after a READ macro was issued and the process queue 
was found to be empty, some data was placed on the process queue. Another 
READ or a CHECK macro should be issued to bring in this data. If SYNAD is 
not specified, a return code of X*00000008' is sent to the appHcation program in 
register 15. 

Neither the wait nor the complete bit in the DECB's ECB is set to 1 by the two 
^'empty-queue" completion codes (X'02000000' and X'0 1000000'). This allows 
the user to wait on ECBs posted in this manner without first having to set the wait 
bit in the ECB to 0. 

User code may test the ECB before issuing a CHECK macro; if the ECB contains 
code X'02000000', the user routine might engage in some other program activity 
rather than issue the CHECK macro and enter a wait state. 



Writing TCAM-Compatible Application Programs 405 



CHECK (BSAM only) 



The CHECK macro instruction causes the application program to be placed in the 
wait state, if necessary, until the associated input or output operation (READ or 
WRITE) is completed. The input or output operation is then tested for errors. If 
no error occurred, control returns to the instruction following the CHECK macro 
instruction. If an error occurred, the routine specified by the SYNAD= operand 
of the input or output DCB macro is given control. If no error routine is specified 
and an error occurred, a return code of X'08' is sent to the user in register 15 after 
the CHECK macro. 



symbol 



decbname 



A CHECK may be issued after each READ and each WRITE in the same order as 
the READ or WRITE macro instructions are issued. If data is available at READ 
time, it is moved at CHECK time into the work area, and the event control block 
(ECB) in the data event control block (DECB) is posted complete with a return 
code of X'TFOOOOOO' (the ECB is contained within the first four bytes of the 
DECB, on a fullword boundary). If there is no data available and a user- 
controlled end of file has not been generated (by the SETEOF macro), the 
apphcation program CHECK macro waits for data. When data is available, 
CHECK causes data movement; when this has been accomplished, the application 
program receives control after the CHECK macro. 

A WAIT macro may be issued rather than a CHECK by specifying the DECB 
address io the ECB= operand of the WAIT macro; this provides a multiple-wait 
capabiHty (see below). The WAIT macro is described in Supervisor and Data 
Management Macro Instructions . 

CHECK has the following format: 



Name 


Operation 


Operands 


[symbol] 


CHECK 


decbname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data event control block created by the 

associated READ or WRITE macro instruction. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and must be 

the same as the dcbname for the associated READ macro. 

Notes: If register notation is used, the specified register number must be enclosed 

in parentheses and the address of the DECB must previously have been loaded 

into a general register, 1 through 12. 



If the user detects an empty-queue completion code in the DECB and does not 
wish to wait impHcitly (CHECK) or expHcitly (WAIT), he may do some other 
processing. After this processing, the completion code will have been altered if a 



c 



406 OS/MFT and OS/MVT TCAM Programmer's Guide 



message has been placed on the associated read-ahead queue. The user must issue 
either CHECK or another READ to cause the pending READ to complete. This 
technique requires one DECB per process queue. 



Writing TCAM-Compatible Application Programs 407 



i 



MCOUNT 



The MCOUNT macro 

• returns, in register 1, the number of complete messages on the input queue; 

• can be issued in an appUcation program before a GET or a READ macro to 
determine how many messages are queued for the application program. 

The count returned in register 1 is for the queues associated with the DCB= 
operand of the MCOUNT macro. If the DCB= operand specifies an outgoing 
data control block, register 1 contains a zero. 

The user must issue an OPEN macro for a DCB before issuing an MCOUNT 
macro referring to that DCB. The MCOUNT macro uses standard register 
linkage. Registers 2 through 13 are saved by TCAM. The user must supply the 
address of a save area in register 13. 

One of the following codes is returned to the application program in register 15 
after the MCOUNT macro executes: 



Code 



Meaning 



X'OOOOOOOO' The MCOUNT macro executed successfully 

X'00000004' TCAM is not in the system 

X'00000008' The specified DCB does not define a 

data set for TCAM messages 
X'OOOOOOOC There is no destination QCB for the entry 

MCOUNT has the following format: 



Name 


Operation 


Operand 


[symbol] 


MCOUNT 


DCB = J name; 
<(r) S 



symbol 



DCB= 



iname / 
(r) S 






Function: Specifies the name of the macro. 

Default: None. This name is optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies an input data control block that defines the message queue for 

the application program. 

Default: None. This operand is required. 

Format: name must conform to the rules for assembler language symbols and 

must be the same as the name specified on the DCB macro. 

Notes: If register notation is used, r may be any general register, 2 through 12, 

that has been loaded with the address of the DCB. The specified register number 

must be enclosed in parentheses. 

If the DCB= operand specifies an outgoing data control block, a count of zero is 
put in register 1 . 



Writing TCAM-Compatible Application Programs 409 



TPDATE 



The TPDATE macro 

• allows the user to specify whether TCAM should delete record delimiters from 
data going to the apphcation program. 

The user must issue an OPEN macro for a DCB before issuing a TPDATE refer- 
ring to that DCB. The TPDATE macro uses standard register linkage. Registers 
2 through 13 are saved by TCAM. The user must supply the address of a save 
area in register 13. 



One of the following return codes is passed to the application program in register 
15 after the TPDATE macro is issued: 

Code Meaning 

X'OOOOOOOO' The TPDATE macro executed successfully. 

X'00000004' TCAM is not in the system. 

X'00000008' The specified DCB does not define a data set for TCAM 

messages. 

TPDATE has the following format: 



Name 


Operation 


Operand 


[symbol] 


TPDATE 


DCB= ( name ( [ ,RECDLM= \ YES ) ] 
j(r) \ <N0 S 

[,DTSAREA= ( area ) ] [,DELETE= K YES \] 
1 (r) f < NO { 



/I 



symbol 



DCB=Jname , 

<(r) 



RECDL!VI=J YES ) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for the assembler language symbols (see the 

entry symbol in the Glossary ). 



Function: Specifies the -data control block that defines the message queue for the 

application program. 

Default: None. Specification required. 

Format: name must conform to the rules for assembler language and must be the 

same as the symbol specified on the DCB macro. If register notation is used r 

may be any general register, 2 through 12, that has been loaded with the address 

of the DCB. The specified register numbers must be enclosed in parentheses. 



Function: Indicates whether the record delimiter specified on the TPROCESS 

macro is to be returned in the low-order byte of register 1. 

Default: NO (this operand is optional) 

Format: YES or NO. 

Notes: If no record delimiter was specified, the value in the low-order byte of 

register 1 will be X*00'. 



{ 



410 OS/MFT and OS/MVT TCAM Programmer's Guide 



DTSAREA= { area i 



!(r) 



DELETE= J YES ) 
JNO S 



Multiple-Wait Capability 



Function: Specifies whether the date, time, and origin of a message obtained by 
the appHcation program are to be placed in the 16-byte area specified. 
Default: None. This operand is optional. 

Format: area must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). If register notation is used, r may be any general 
register 2 through 12. The specified register number must be enclosed in par- 
entheses. 

The format of area is: 





YY 


DD 


DC 


HHMM 


SS 


NN 


C 


C 


c 


c 


c 


c 


c 


c 



where 

YY = last two digits of the year (packed decimal) 

DDD = day of the year (packed decimal) 

C = sign character (for unpacking 

HH = hours (packed decimal) 

MM = minutes (packed decimal) 

SS = seconds (packed decimal) 

NN = hundredths of seconds (packed decimal) 

CCCCCCCC = source (character) 

If the date and time are not available, the date and time fields will contain zeros. 
If the source is not available, the source field will default to blanks. 
Notes: This operand requires that DATE=YES be specified on both the 
TPROCESS and the PCB macros for the application program. 



Function: Specifies whether the record dehmiter is to be deleted from the record 

sent to the appHcation program. 

Default: NO. Specification optional. 

Format: YES or NO. 

Notes: The TPDATE macro must be coded before the GET or READ macros 

when record delimiters are to be deleted from data going to the application 

program or when the date, time, and source are to be provided. 



The user may achieve a multiple-wait capability by issuing more than one READ 
macro to more than one process queue and then issuing a WAIT macro. In the list 
specified by the ECBLIST= operand of the WAIT macro, the user would place 
the addresses of the DECBs associated with the READ macros issued, as well as 
any other DECBs associated with the appUcation program. A message satisfying a 
pending READ macro would cause a completion code of X'40000000' to be 
placed in the associated ECB. After the WAIT macro, one or more CHECK 
macros (or perhaps READ macros) should be coded so that the data will be 
moved into the user's work area. For information on the WAIT macro, see 
Supervisor and Data Management Macro Instructions. 



After the DECB address is made available to the MCP at the time of the first 
READ operation, the MCP posts (with X'40') that DECB when a message or 



Writing TCAM-Compatible Application Programs 41 1 



buffer is enqueued on the previously empty read-ahead queue. This impUes that 
the DECB may be posted complete after CHECK, but before the next READ. 
The user should handle this possibility in case of a multiple wait (the DECB is 
always ehgible for posting and should never be waited for unless the user is ready 
to process another work unit). 

Example: 

In the following section of code the user issues READ macros specifying DCBs 
associated with three process queues (DCBA, DCBB, DCBC), and then issues a 
WAIT macro specifying one event and having an ECBLIST= operand pointing to 
a list of addresses of the DECBs associated with the READ macros. When a 
pending READ macro is satisfied, a completion code of X'40000000' is placed in 
the ECB associated with the READ, and the address of the EBC is placed in 
register 1 . If only one event is specified, the user may issue a CHECK macro 
specifying register 1 ; this macro moves the message satisfying the READ into its 
own work area (AREAA if READA was satisfied, AREAB if READB was 
satisfied, AREAC if READC was satisfied). 



READA 


READ 


DECBA , SF , DCBA , AREAA 


READB 


READ 


DECBB , SF , DCBB , AREAB 


READC 


READ 


DECBC , SF , DCBC , AREAC 




WAIT 


1 ,ECBLIST=DECBLIST 




LA 


2, DECBLIST 


LOOP 


L 


1.0( ,2) 




LA 


2,iX{ ,2) 




TM 


0(1), COMP 




BNO 


LOOP 


CHEKIT 


CHECK 

Processing 
Code 


( 1 ) 


DECBLIST 


DS 


OF 




DC 


A( DECBA) 




DC 


A( DECBB ) 




DC 


XL1 '80' 




DC 


AL3( DECBC ) 


AREAA 


DS 


lOOF 


AREAB 


DS 


200F 


AREAC 


DS 


300F 


COMP 


EQU 


X'40' 



END 



Figure 3 1 . Example of Multiple-Wait Capability 



The instruction immediately preceding the last address in the list causes the 
high-order bit of the last entry to be turned on; this is an OS requirement. 

Application Program Error Exits 

The input and output DCB macros for TCAM-compatible application programs 
permit the application programmer to specify an exit to be taken when certain 
errors occur during transfer of data between the MCP and the appHcation pro- 
gram. This is the SYNAD exit, specified in the SYNAD= operand of the DCB 
macro. 



The open or closed, user subroutine whose address is specified in the SYNAD = 
operand receives control when certain errors occur. The user subroutine receives 
input identical to that provided by QSAM and BSAM for their SYNAD exit (as 



( 



412 OS/MFT and OS/MVT TCAM Programmer's Guide 



Input to the SYNAD Routine 



explained in Supervisor and Data Management Macro Instructions ). This 
implies that SYNADAF or SYNADRLS macro instructions may be issued in the 
SYNAD routine. The next section details the register contents on entry to the 
SYNAD routine and the contents of the status indicator field for the SYNAD 
routine, while the following section contains information on using the SYNADAF 
macro. 

The SYNAD routine specified by an input DCB macro is given control if 1 ) 
message-type processing has been specified (by coding U in the OPTCD= 
operand), 2) the message to be transferred by the current GET or READ macro is 
larger than that portion of the work area available to it, and 3) no position field is 
specified for this work area (OPTCD= does not specify C). In his SYNAD 
routine, the user must close and reopen this set before issuing another GET or 
READ; otherwise, TCAM will not continue to function properly. The routine is 
entered after a GET or CHECK macro is issued. If the error condition occurs and 
SYNAD is not specified, TCAM returns a completion code of X^OOOOOOOH' in 
register 15 following GET or CHECK. In this case, user code should close the 
data set. 

The SYNAD routine specified by an output DCB macro is given control when one 
of two logical output errors occur: 

1. The position field contains a value that is invalid (not X'40\ X'FT, XT2\ or 
XT3') or that indicates that the current position of the message is out of 
sequence (for example, the position field indicates that this is the first portion 
of the message, but the position field for the previous work unit did not indicate 
end-of-message). 

2. The destination name in the destination field is not a valid entry in the terminal 
table. 

For BSAM, this exit is entered only from the CHECK routine. If SYNAD= is not 
specified, condition (1) above results in a completion code of X'00000008' in 
register 15, while condition (2) results in a code of X'OOOOOOOC. 



Input to SYNAD from TCAM/SAM access method modules is compatible with 
SAM. Register contents on entry to the SYNAD routine are as follows: 

Register Bits Meaning 

8-31 Address of the data event control block (DECB) for BSAM; 

address of status indicators for QSAM. 
Bit is on for error caused by GET or READ. 
Bit is on for error caused by PUT or WRITE. 
Bit is on if user specified an invahd destination (PUT or WRITE). 
Address of associated data control block (DCB). 
Contents before the macro instruction was issued. 

Return address. 

Address of error analysis routine specified by the SYNAD= 

operand of the input DCB. 

Word five (5) of the DECB (DECB+16) contains the status indicator address for 
BSAM support. Status indicators for the SYNAD routine are as follows: 



1 







1 




4 




8-31 


2-13 


8-31 


14 


8-31 


15 


8-31 



Writing TCAM-Compatible Application Programs 413 



SYNADAF 



Offset from status 
Indicator address 


Meaning 


Byte 


Bit 


Command reject (work units out of sequence). 
Incorrect length (work area overflow). 


+2 
+ 13 


a 

1 



All other fields in the SAM-compatible status indicator field are unused by 
TCAM. Main storage for this block is allocated at OPEN time if the SYNAD= 
keyword is coded in the DCB macro instruction or if provision is made by an 
alternate source. 



If the user issues a SYNADAF macro specifying BSAM or QSAM in his error 
analysis routine, he receives the following values in the specified registers: 

Register 1 contains the address of a buffer containing a message describing the 
TCAM/SAM error. The message consists of EBCDIC information and is in 
the form of a variable length record (see table below). 

Register contains a return code of X'OO', right-adjusted. 

See Supervisor and Data Management Macro Instructions , for further informa- 
tion on the use of SYNADAF and SYNADRLS. 



Format of TCAM/SAM SYNADAF Message Buffer 



Bytes 


Contents 


0-7 


SAM variable (or variable blocked) length prefix 


8-49 


(character blanks) 


50-57 


job name 


58 


, (character comma) 


59-66 


stepname 


67 


, (character comma) 


68-73 


(character blanks) 


74 


, (character comma) 


75-82 


ddname (name of DD statement in which QNAME= 




parameter is coded) 


83 


, (character comma) 


84-89 


macro format (GET, PUT, READ, or WRITE) 


90 


, (character comma) 


91-105 


error description (WORKAREA OFLOW, INVALID DEST, or 




SEQUENCE ERROR) 


106 


, (character comma) 


107-120 


**************** 


121 


, (character comma) 


122-125 


TCAM 



{ 



414 OS/MFT and OS/MVT TCAM Programmer's Guide 



Network Control Facilities 

TCAM provides facilities for dynamically controlling the telecommunications 
network through macro instructions issued in an application program. Three 
macros are provided to allow the contents of a control block to be examined: 
TCOPY, ICOPY, and QCOPY. Two macros are provided to allow modification 
of the contents of a control block: TCHNG and ICHNG. TCAM also provides 
the MRELEASE macro, which releases messages queued for an intercepted 
station, and the MCPCLOSE macro (discussed in Activation and Deactivation 
of the MCP Interface in this chapter), which initiates closedown of the Message 
Control Program. These macros are described in detail below. The facilities 
provided by these macros are also available using the operator commands of the 
operator control facihty (see each macro description below). 

In order to execute, TCOPY, QCOPY, and TCHNG require at least one open 
input or output DCB for this apphcation program task. 

Application-Program Network-Control Macros 



Interrogation 


Capability 


• TCOPY 


Copy the contents of a designated terminal table entry and its 




associated option fields into a work area. 


. ICOPY 


Copy the contents of a specified line's invitation list into a 




work area. 


• QCOPY 


Copy the contents of the queue control block (and its related 




priority QCBs) associated with a terminal (or process entry) 




into a work area. 



Modification Capability (Password Protection Optional) 



INTRO 



TCHNG 



ICHNG 



MRELEASE 
MCPCLOSE 



PASSWRD= \ chars 



\ chars / 



Defines the password. 



Place contents of work area into a terminal table entry and its 

associated option fields. 

Replace a specified invitation Hst with the contents of the 

work area, or activate or deactivate all entries in the specified 

list. 

Activate a destination for receipt of messages from the CPU. 

Initiate termination of the TCAM message control program. 



In addition to these macros, TCAM provides the user with the capabiHty of 
defining his application program as a secondary operator control station (by 
coding the SECTERM= operand of the TPROCESS macro) and of entering 
operator commands from it by means of PUT or WRITE macros. Responses to 
these commands are sent to the destination specified by the ALTDEST= operand 
of the TPROCESS macro creating the terminal table, process entry associated 
with the PUT or WRITE macro. For more information on the use of an applica- 
tion program as an operator control station, see Entering Operator Commands 
from an Application Program in the chapter Using TCAM Service Facilities. 






Protection against unauthorized use of the ICHNG, TCHNG, MRELEASE, and 
MCPCLOSE macros is provided by the PASSWRD= operand of these macros. 
The password specified must be the same as the password specified by the 



Writing TCAM-Compatible Application Programs 415 



PASSWRD= operand of the INTRO macro, otherwise, the application program 
macro is ignored. 

The user might code a special application program designed solely to modify the 
teleprocessing system in the event of errors or other unusual conditions. For 
example, he might code ERRORMSG or REDIRECT macros in an inmessage 
subgroup handhng messages coming in over a hne group. These macros could test 
various bits in the message error record, and when these bits were on, the macros 
could direct a special error message, or the message being handled when the error 
occurred, to the process queue for the appHcation program. The application 
program could fetch error messages by GET or READ macros, analyze them, and 
issue operator commands (if it were designated a secondary operator control 
station by the TPROCESS macro) or network-control macros to modify the 
system in a manner appropriate to the error detected. 

The user is required to have at least one open TCAM DCB in the application 
program task in which these network-control macros are issued. To insure 
reliability, the statname operand of the TCOPY and MRELEASE macros arid the 
termname operand of the TCHNG and QCOPY macros should not exceed the 
value coded in the MAXLEN= operand of the TTABLE macro. Since the user is 
not required to place the name in an eight-byte field, left-adjusted and padded 
with blanks, TCAM cannot check the validity of a name with respect to length. 
This may result in finding a match in the termname table that exceeds the 
maximum termname length in the MCP. 



( 



416 OS/MFT and OS/MVT TCAM Programmer's Guide 



TCOPY 



The TCOPY macro 

• permits examination of the contents of a terminal table entry and its associated 
option fields; 

• is optional in a TCAM appHcation program. 

TCOPY moves the contents of a designated terminal table entry to a work area, 
together with the contents of any option fields that are associated with the entry. 
The terminal table entry may be any of the entry types. 

Various functions of TCOPY are also provided by the STSTATUS and 
OPTFIELD operator commands (see the Operator Commands section in Using 
TCAM Service Facilities), Execution of TCOPY alters the contents of registers 
Hand 15. 

The dummy section (DSECT) describing the single, line, and group, terminal table 
entries has the following format: 



The length of the TRMOPT field is variable. If no OPTION macros are coded in 
the MCP, no space is allocated for the TRMOPNO field, the TRMOPTBL field, 
or the TRMOPT field. A variable number of device-characteristics fields follow 
the TRMOPT field (if OPTION macros are coded) or the TRMCHCIN field (if 
no OPTION macros are coded). The first byte of each device-characteristics field 
contains the binary length of the rest of the field; the rest of the field contains the 
device-dependent data. 

In addition to the contents of the terminal table entry itself, TCOPY moves the 
contents of any option fields associated with a terminal table entry into the 



TRMSTATE 


TRMDESTQ 



+1 



■^H 



TRMINSEQ 



TRMOUTSQ 






+4 



+6 



TRMALTD 



TRMDEVFL 



iH 

^h 

TRMTEMPRi TRMSENSE 

IH 

^h 



+8 



+10 



TRMSIO 



+12 



+14 



TRMCHCIN 



TRMOPNO 



TRMOPTBL 



iH 



+16 



+17 



+18 



TRMOPT 



Start of device 
characteristics field 



+20 

Figure 32. Terminal Table DSECT for Single, Line, and Group Entries 



Writing TCAM-Compatible Application Programs 4 1 7 



specified work area. The first option field immediately follows the last device- 
characteristics field in the work area. A two-byte field named TRMOPTBL, 
located at an offset of 18 bytes from the beginning of the terminal table entry, 
contains the offset from the beginning of the terminal table entry to the beginning 
of the first option field in the user's work area. 

The user must ensure that his work area is large enough to accommodate the 
largest possible string of data moved into it by TCOPY. (If the work area is not 
large enough to accommodate the data, the contents of main storage adjoining the 
work area are overlaid and lost.) The user may determine the length of the longest 
possible string of data that the TCOPY macro can move into his work area by 
looking at the assembly listing for his MCP. Under each TERMINAL, TLIST, 
TPROCESS, and LOGTYPE macro expansion are control sections having 
TERMINAL ENTRY, OPTION OFFSETS, and DEVICE-DEPENDENT FIELDS in their 
comment fields. These CSECTs indicate the length of the terminal table entry, 
the option-field offsets, and the device-characteristics fields, respectively. The 
user should find the sum of these lengths for each terminal table entry he might 
wish to copy using TCOPY, and add to this sum the total length of the option 
fields associated with that entry. The work area named in TCOPY should contain 
a number of bytes equal to or greater than the largest sum obtained in this way. 



One of the following return codes is returned to the apphcation program in 
register 15 after the TCOPY macro is issued: 



Code 

X'OOOOOOOO' 
X*00000008' 
X'OOOOOOOC 



X'00000020' 



Meaning 

The TCOPY macro executed successfully. 

TCAM is not in the system. 

A TCAM apphcation-program DCB is not open; at least one 

input or output DCB must be open in order for this macro to 

execute. 

An invahd station name is specified in the field of the TCOPY 

macro (that is, no such entry exists in the terminal table). 



c 



symbol 



For a complete description of terminal table entries, see the discussion in section 
5, Data Area Layouts , in the TCAM PLM . 

TCOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


TCOPY 


statname, areaname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



statname 



Function: Specifies the name of the station whose contents are to be moved to 

the work area. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be the 

same as the name for the station specified in the MCP terminal table. 



c 



418 OS/MFT and OS/MVT TCAM Programmer's Guide 



Notes: If register notation is used, the register must previously have been loaded 
with the address of a field containing the entry name. The name must be left- 
adjusted and padded with blanks to equal the longest allowable station name. 
Permissible registers are 0, 2 through 12, 14, and 15. 



Function: Specifies the name of the work area into which the contents of the 
terminal table entry and its associated option fields are to be placed. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: If register notation is used, the register must previously have been loaded 
with the address of the work area. Framing parentheses must be coded. Permissi- 
ble registers are 1 through 12, 14, and 15. 



Writing TCAM-Compatible Application Programs 419 



ICOPY 



The ICOPY macro 

• permits examination of the contents of an invitation list; 

• is optional in a TCAM application program. 

The ICOPY macro moves the contents of a designated invitation list to a work 
area. The function of ICOPY is not provided by the operator control facility. 
However, the ACTVATED and STATDISP operator commands cause display of 
the active and inactive terminals in a list and the status byte of an invitation list, 
respectively. Execution of ICOPY alters the contents of registers 14 and 15. 

One of the following codes is returned to the application program in register 15 
after the ICOPY macro is issued: 

Code Meaning 

X^OOOOOOOO' The ICOPY macro executed successfully. 

X'00000004' An invalid relative line number is specified in the rln field of 

the ICOPY macro. 
X^00000008' TCAM is not in the system. 

X'00000020' The name specified is not the name of an opened, TCAM line 

group DCB. 

For a complete description of the invitation list, see Defining Terminals and 
Line Control Areas. 

Figure 33 below illustrates the format of an invitation list with three entries. 
Individual fields in the invitation list are discussed following the illustration. 
Control Information: 

Byte Meaning 

Indicates the total number of entries (both active and inactive) in this 
invitation list. All zeros in this byte indicates that this invitation list is for 
an output-only line (stations on this line cannot enter messages). This 
invitation list contains three entries. 

1 Indicates the number of active entries in this invitation Hst (an active 
entry is one that is currently eligible to be polled). This invitation list 
contains two active entries. 

2 Indicates the number of bytes, including a one-byte index used by TCAM, 
in each entry in this Hst. The sample invitation Hst in the illustration 
above contains entries of three bytes each. The index byte must be the 
last byte in each entry. 

3 Bits through 5 in byte 3 are control bits used by TCAM (their contents 
mustnot be altered). If bit 6 is on, this is an active invitation list (it is 
being polled); if it is off, this invitation Hst is not currently eligible to be 
polled. If bit 7 is on, the Auto Poll feature is being used on the line corre- 
sponding to this invitation list; if it is off, programmed polling is in effect 
(this bit is meaningless if bit 6 if off). Bits 6 and 7 are both on in the 
sample invitation list, thus, this Hst is currently being polled by using the 
Auto PoH feature. 



i 



420 OS/MFT and OS/MVT TCAM Programmer's Guide 



Control 
Information 



Active 
Entries 



Delimiter 



Inactive 
Entries 



X'03' 



X'02' 



X'03' 



T 



CPU identifier ■ 

J I 



byte: 



TCAM control bits 

I I I I I 



bit: 1 2 3 4 5 6 7 



polling 
characters 

L_ 



H 


X'FE' 


H 


H 




U 



14 15' 



poi I ing 
characters 



15 



16 



1-byte 
index used 
by TCAM 



polling 
characters 



10 



12 



1-byte 
jndex used 
by TCAM 



17 



1-byte 
index used 
by TCAM 



13 



14* 



Figure 33. Sample Invitation List Containing Three Entries 



4-7 For non-buffered terminals, bytes 4 through 7 contain either ail zeros or 
the address of a field that identifies the central processing unit into which 
TCAM is loaded. For buffered terminals, bytes 4 through 7 indicate the 
following: 

Byte Meaning 

4 A one-byte count of the terminals on this line to which TCAM is current- 
ly sending. 

5 Contains X'Ol' if the line is eligible for Auto Poll. 

6 (unused) 

7 A one-byte count of the total number of terminals on the line. 
The contents of bytes 4 through 7 must never be altered. 

Active Entries: 

Byte Meaning 

8-10 Bytes 8 through 10 represent the first active entry in this invitation list. 

The polling characters for a station (or a component) are contained in the 



Writing TCAM-Compatible Application Programs 42 1 



11-13 



two-byte field starting at byte 8; although all the entries in this list use 
two-byte fields to contain polling characters, other lengths may be used. 
Byte 10 contains an index used by TCAM; this index must not be altered. 

Bytes 1 1 through 1 3 represent the second active entry in this sample 
invitation Hst. (The same general discussion of bytes 8-10 also applies 
here.) 



symbol 



grpname 



Delimiter: 

Byte Meaning 

14 For an invitation list containing entries for BSC devices, an EOT charac- 

ter followed by XTE' serves as a delimiter to indicate the end of the list 
of active entries. For start-stop devices, the delimiter is XTE' without an 
EOT character. 

In this sample invitation list, entries are for start-stop devices. Two, active, 
three-byte entries precede the delimiter, and byte indicates that there are three 
entries; consequently, there is a third entry in this invitation list (and since it 
follows the delimiter, it is an inactive entry). The delimiter must not be altered. 

Inactive Entry: 

Byte Meaning 

15-17 Bytes 15 through 17 represent the first inactive entry in this invitation list. 
(The same general discussion of bytes 8-10 also appHes here, except that 
this is an inactive entry.) 

ICOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


ICOPY 


grpname,rln,areaname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the Une group containing the line whose invita- 
tion Hst is to be displayed. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols, and be the 
same as that specified in the DDNAME= operand of the DCB macro for the hne 
group. 

Notes: If register notation is used, the register specified must have previously 
been loaded with the address of a field containing the grpname . Permissible 
registers are 1-12, 14, and 15. Framing parentheses must be coded. The name 
must be left-adjusted and padded with blanks to eight characters. 



422 OS/MFT and OS/MVT TCAM Programmer's Guide 



rin 



Function: Specifies the relative line number, within the line group, of the line 
whose invitation list is to be displayed. 
Default: None. This operand is required. 
Format: Unframed decimal integer greater than zero. 
Maximum: 255 

Notes: If register notation is used, the relative line number must previously have 
been loaded (in binary form and enclosed in parentheses) in the register designat- 
ed. Permissible registers are 0, 2 through 12, 14, and 15. 



Function: Specifies the name of the work area into which the designated invita- 
tion Ust is to be moved. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The number of bytes to be allowed for each entry in the list depends upon 
the type of entry in the Ust. 

If register notation is used, the register number specified must be enclosed in 
parentheses and must contain the address of the work area. Permissible registers 
are 2 through 12, 14, and 15. 



Writing TCAM-Compatible Application Programs 423 



QCOPY 



The QCOPY macro 

• permits examination of a queue control block; 

• is optional in a TCAM application program. 

QCOPY causes the contents of both a destination queue control block (QCB) and 
its related priority QCBs to be copied into a designated work area. The QCB is an 
internal TCAM control block associated with a destination queue. For a complete 
description of queue control blocks, see the discussion in Section 5, Data Area 
Layouts in the TCAM PLM . A master QCB is 40-bytes and always has associat- 
ed with it at least one priority QCB (even if priorities are not specified for this 
destination QCB's corresponding station in the station's LEVEL= operand of its 
TERMINAL macro). Each priority QCB is 28 bytes; therefore, the formula for 
determining the number of bytes needed in the work area in the user's application 
program is: 

68 + 28n bytes 

where n is the number of different priorities specified (for the station whose 
associated QCB is being copied) in the station's LEVEL= operand of its 
TERMINAL macro. 

Part of the function of QCOPY is also provided by the QSTATUS and 
RLNSTATN operator commands (see their descriptions in the Operator 
Commands section of the chapter Using TCAM Service Facilities), 

One of the following return codes is passed to the application program in register 
15 after the QCOPY macro is issued: 



Code 

X'OOOOOOOO' 
X'00000004' 

X'00000008' 
X'OOOOOOOC 

X'00000020' 



X'00000080' 



Meaning 

The QCOPY macro executed successfully. 

Invahd terminal table entry type (for example, distribution Ust 

or cascade Ust is specified in the termname field). 

Invahd terminal table entry type (for example, distribution list 

A TCAM application program DCB is not open; for this macro 

to execute, at least one input or output DCB must be open. 

An invalid station name is specified in the termname field of 

the QCOPY macro (that is, no such entry exists in the terminal 

table). 

The iterative process has been completed the number of times 

specified by the LIMIT=operand. 



QCOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


QCOPY 


termname ,areaname[,LIMIT= (integer ) ] 

((register)/ 



i 



424 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



termname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the terminal table entry whose QCB is to be 

displayed, or the name of the last terminal table entry that had its QCB displayed 

if using iterative processes and selection criteria. See notes following the LIMIT= 

operand. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 

identical to the name of the terminal table entry. If using iterative processes and 

selection criteria, must be blank. If register notation is used, the specified register 

number must be enclosed in parentheses, and the register must contain the address 

of a field containing the name of the entry. The name must be left justified and 

padded with blanks to the length of the longest allowable station name in the 

table. 



LIMIT=rinteger )^ 
I (register) ) 



Function: Specifies the name of the work area into which the contents of the 

designated QCB are to be placed. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. If register 

notation is used the specified register number must be enclosed in parentheses, 

and the register must have been loaded previously with the address of the work 

area. Permissible registers are 2 through 12. 

Function: Indicates that an interactive process and selection criteria are to be 
used. The number specified is the minimum number of messages for which the 
routine will select a terminal table entry. 
Default: None. Specification optional 
Format: LIMIT=integer or LIMIT = (register) 
Minimum: 1 
Maximum: 4095 

Notes: If register notation is used a register number may be enclosed in parenthes- 
es or a symbol equated to a register number may be enclosed in parentheses. 
Registers 2 through 12 may be used. If this operand is not coded, the QCOPY 
routine will display the QCB for the designated terminal name. If coded, a 
terminal name subsequent to the one specified in operand 1 with at least the limit 
number of messages in its queue will be returned in the original terminal name 
area and its QCB will be displayed. 

QCOPY iterative processes and selection criteria enable the user to display all 
QCBs for terminals having some threshold number of messages queued. The 
threshold is specified in the LIMIT = operand. 



Writing TCAM-Compatible Application Programs 425 



TCHNG 



symbol 



The TCHNG macro 

• places specified data in a terminal table entry and its associated option fields; 

• is optional in a TCAM application program. 

TCHNG causes the contents of a designated work area to replace the contents of 
a specified terminal table entry. The TCOPY macro may be used to move the 
contents of a terminal table entry to a work' area where the contents are manipu- 
lated as desired (see the discussion of the TCOPY macro for a description of a 
terminal table entry). The TCHNG macro is then used to move the modified 
entry back to the terminal table. Option fields are modified in the same manner 
by this macro. 

All necessary information for proper execution of TCAM must be placed in the 
terminal-table entry in proper form. The contents of option fields may also be 
modified by the DATOPFLD operator command (see the Operator Commands 
section of this publication). 

One of the following return codes is returned to the application program in 
register 15 after the TCHNG macro is executed: 

Code Meaning 

X'OOOOOOOO' The TCHNG macro executed successfully. 

X'00000008' TCAM is not in the system. 

X'OOOOOOOC A TCAM application program DCB is not open; at least one 

input or output DCB must be open for this macro to execute. 

X'00000014' Either a) an invalid protection password is specified as the 

PASSWRD= operand of the TCHNG macro; or b) the 
PASSWRD= operand is not specified in the TCHNG macro 
(and it must be specified because the INTRO macro's 
PASSWRD= operand specifies a protection password; code 
this operand exactly as it is coded in the INTRO macro). 

X'00000020' An invalid station name is specified in the termname field of 

the TCHNG macro (that is, no such entry exists in the terminal 
table). 



TCHNG has the following format: 



Name 


Operation 


Operands 


[symbol] 


TCHNG 


termname,areaname [,PASSWRD= chars] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



{ 



426 OS/MFT and OS/MVT TCAM Programmer's Guide 



termname 



PASSWRD=chars 



Function: Specifies the name of the terminal table entry whose contents are to be 
replaced by the contents of the designated work area. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name of the station as specified in the terminal table. 
Notes: If register notation is used, the specified register number must be enclosed 
in parentheses, and the register must contain the address of a field containing the 
name of the terminal table entry, left-adjusted and padded with blanks. The field 
must be as long as the longest allowable station name, a maximum of eight charac- 
ters. Permissible register are 2 through 12. 



Function: Specifies the name of the work area from which the information is to 

be moved into the terminal table entry. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The first byte of the entry receives the first byte of data in the work area, 

which must accordingly be the status byte. The work area should be at least as 

long as the longest terminal table entry that will be changed. 

If register notation is used, the specified register number must be enclosed in 
parentheses, and the register must contain the address of the work area. Permissi- 
ble registers are 2 through 12. 

The new entry must contain, in proper form, all information necessary for success- 
ful operation of TCAM. See the description of the terminal table entries in the 
chapter Defining Terminal and Line Control Areas. 



Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand of the INTRO macro was coded, 
this operand is required. Otherwise, specification optional. 
Format: One to eight, nonblank characters, unframed. 

Notes: If coded, this operand must specify the same characters as were specified 
in the INTRO macro. 



Writing TCAM-Compatible Application Programs 427 



ICHNG 



The ICHNG macro 

• modifies an invitation list; 

• is optional in TCAM application programs. 

ICHNG causes the contents of a designated work area to replace the contents of a 
specified invitation Hst, or the stations in the specified list to be activated or 
deactivated for entering messages (if they are polled stations). ICOPY macro may 
be used to move the contents of an invitation list to a work area where the con- 
tents are manipulated as desired. The ICHNG macro may then be used to move 
the modified Ust contents back to the invitation Ust. For a complete description of 
the invitation hst, see Establishing Contact in the chapter Defining Terminal 
and Line Control Areas in this book. A sample invitation list containing three 
entries is presented in the discussion of ICOPY. 

If the macro is used to replace the contents of a specified invitation hst with the 
contents of a work area, all necessary information for proper execution of TCAM 
must be placed in the invitation Hst in proper form. Entries in an invitation list 
may also be activated or deactivated by the ENTERING, NOENTRNG, 
NOTRAFIC, and ACTVBOTH operator commands. The Auto Poll facility may 
be activated or deactivated by the AUTOSTRT and AUTOSTOP operator 
commands, respectively (if the autopoll bit is turned on in the UCB). See the 
description of these commands in the Operator Commands section of this publi- 
cation. Stopping and starting of Unes before and after changing the contents of an 
invitation Hst is handled automaticaUy for the TCAM user. Execution of ICHNG 
alters the contents of registers 14 and 15. /^ 



One of the f oUowing codes is returned to the appHcation program in register 1 5 
after the ICHNG macro is issued: 

Code Meaning 

X^OOOOOOOO' The macro executed successfuHy. 

X*0000000r The DCB for the line group specified by grpname is not open. 

X*00000004' An invaHd name is specified for the grpname operand of the 

ICHNG macro. 
X*00000008' An invalid relative Hne number is specified in the rln field of 

the ICHNG macro (that is, no such relative number exists for 

the group). 
X^OOOOOOOC TCAM is not in the system. 

X'00000014' The PASSWRD= operand is not specified or is specified 

incorrectly in the ICHNG macro (and it must be specified 

because the INTRO macro's PASSWRD= operand specifies a 

protection password; code this operand exactly as it is coded in 

the INTRO macro). 
X'00000020' The grpname is invalid. 

ICHNG has the following format: 



i 



i 



428 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



grpname 



rln 



Name 


Operation 


Operands 


[symbol] 


ICHNG 


grpname,rln,^areaname| 
.^ACT > 
(dEACT )[,PASSWRD=chars] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the line group containing the line whose invita- 
tion list is to be modified. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name specified on the DD statement associated with the line 
group. 

Notes: If register notation is used, the specified register number must be enclosed 
in parentheses, and the address of a field containing the grpname must previously 
have been loaded into the general register specified. The name must be left- 
adjusted in the field and padded with blanks to equal eight bytes. Permissible 
registers are 1 through 12, and 14. 

If the DCB for the line group has not been opened, ICHNG is not executed and a 
return code of X'OT is set in register 15. 



Function: Specifies the relative line number within the Une group of the Hne 

whose invitation list is to be modified. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 255 

Notes: If register notation is used, the register number specified must be enclosed 

in parentheses, and the register must previously have been loaded with the relative 

line number in binary format. Permissible registers are 1 through 12, and 14. 



areaname 

ACT 

DEACT 



Function: Specifies the type of modification or the modification itself. 

Default: None. This operand is required. 

Format: areaname, ACT, or DEACT. areaname must conform to the rules for 

assembler language symbols. 

Notes: areaname specifies the name of the area that contains the new invitation 

list. The first byte of the invitation hst receives the first byte of the data in the 

work area, which accordingly must be the first byte of the invitation list control 

word. 






ACT causes the activation of all entries in the specified invitation list. DEACT 
causes deactivation of all entries in the specified invitation Ust. No further polUng 
will occur until the list is reactivated by an ICHNG macro specifying ACT, or an 
ENTERING operator command. 



Writing TCAM-Compatible Application Programs 429 



Register notation may be used for areaname . If register notation is used, the 
specified register number must be enclosed in parentheses, and the address of the 
work area must previously have been loaded into the register specified. Permissi- 
ble registers are 1 through 12, and 14. 

If areaname is specified, the new invitation list must contain, in proper format, all 
information necessary for successful operation of TCAM. See the description of 
the ICOPY macro for the format of the control word and of an invitation list. 

PASSWRD=chars 

Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand of INTRO was coded, this operand 
is required. Otherwise, specification optional. 
Format: One to eight nonblank characters, unframed. 

Notes: If coded, this operand must specify the same characters as specified by the 
PASSWRD= operand of INTRO. If the characters do not agree, or if INTRO 
specified PASSWRD= but this macro does not, ICHNG does not execute. 



^ 



430 OS/MFT and OS/MVT TCAM Programmer's Guide 



symbol 



MRELEASE 



The MRELEASE macro 

• releases messages queued for a destination, 

• reactivates a destination made inactive by a HOLD macro or a SUSPXMIT 
operator command. 

The MRELEASE macro releases messages queued for a station. This macro has 
the same effect as the RESMXMIT operator command. 

One of the following codes is returned to the appHcation program in register 1 5 
after the MRELEASE macro is issued: 

Code Meaning 

X'OOOOOOO' The MRELEASE macro executed successfully. 

X*000000r There is no open DCB in the program. 

X* 0000004' The MRELEASE macro did not execute because the station is 

already receiving its queued messages. 
X^OOOOOOC TCAM is not in the system. 
X*0000014' The MRELEASE macro did not execute because either 

a) the protection password specified in the PASSWRD= operand 
does not match the protection password specified by the 
PASSWRD= operand of the INTRO macro, or 

b) a protection password is not specified in the PASSWRD= 
operand of the MRELEASE macro (and it must be specified 
because the INTRO macro's PASSWRD= operand specifies a 
protection password). Code the PASSWRD= operand exactly as 
it is coded in the INTRO macro. 

X'0000018' The MRELEASE macro did not execute because 

a) statname is not a single entry in the terminal table, 

b) there is no HOLD macro in the system, or 

c) the station uses main-storage queues only. 

X'0000020' The MRELEASE macro did not execute because an invalid station 
is specified in the statname field of the macro. 

MRELEASE has the following format: 



Name 


Operation 


Operands 


[symbol] 


MRELEASE 


statname [,PASSWRD= chars ] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



statname 






Function: Specifies the name of the station that is now to receive its queued 

messages. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols and be the 



Writing TC AM-Compatible Application Programs 43 1 



PASSWRD== chars 



same as the name of the terminal entry. 

Notes: If register notation is used, the address of a location containing the name 

of the station must be placed in the general register, 2 through 12, that is indicated ^ 

in parentheses. The name must be left-adjusted and padded with blanks to the 

length of the longest station name. 

Function: Specifies the protection password that enables only qualified a